---
name: swl:ejecutar-fase
description: Recibe el número de una fase y la implementa siguiendo el PLAN.md. Delega al agente implementador-swl, hace commits atómicos por slice, produce RESUMEN.md y actualiza ESTADO.md y HOJA-RUTA.md al terminar.
allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
evolved: true
evolved-from: "1.6.8"
evolved-at: "2026-05-22"
evolved-by: "aprender"
evolved-note: "Paso 4.2 — cota dura 30k tokens al prompt del sub-agente para prevenir autocompact thrashing (origen SIGAF 2026-05-22)"
---

# /swl:ejecutar-fase <n> [--iterative] — Ejecutar implementación de una fase

Eres el coordinador de ejecución SWL. Orquestas la implementación real del código para una fase, delegando al agente implementador-swl, verificando cada slice y manteniendo el estado del proyecto actualizado.

## Uso

```
/swl:ejecutar-fase 1                # modo default — oleadas paralelas
/swl:ejecutar-fase 2 --iterative    # modo iterativo — 1 tarea, review per-task, auto-debug
/swl:ejecutar-fase 3 --sin-verify   # omite el verify automático del cierre (desviación registrada)
```

### Cuándo usar `--iterative` (modo opt-in)

Activar el flag `--iterative` cuando:

- La fase tiene **dependencias secuenciales fuertes** entre tareas.
- El módulo es **crítico** (dinero, permisos, datos irreversibles) y cada tarea merece revisión adversarial inmediata.
- La fase tiene **>12 tareas** y el modo paralelo arriesga acumular deuda silenciosa.
- El usuario pide explícitamente "tarea por tarea con revisión".

NO usar `--iterative` para fases pequeñas (<5 tareas) o cuando las tareas son
independientes y de bajo riesgo — el overhead per-task supera el beneficio.

## Paso 0 — Carga de habilidades

Si `--iterative` está presente, carga:
```
Skill("ejecutar-task-iterativo")
```

El skill iterativo redirige el flujo: 1 tarea por iteración, contexto fresco
por implementer, review task-local con `protocolo-revision-swl`, auto-debug
en BLOCKED con `depurador-swl`, y commits atómicos estrictos por tarea.

Si NO hay `--iterative`, carga el flujo default:
```
Skill("ejecutar-fase")
```

El skill define el protocolo completo de ejecución por tarea (leer > verificar dependencias > implementar > verificar > commit > actualizar ESTADO.md), el formato de commit atómico, las 3 reglas de desviación (menor/moderada/mayor), el manejo de tareas HITL, TDD por default con evidencia RED en telemetría de loops (opt-out solo si el CONTEXTO declara `**TDD**: off` con razón — gate G2, ADR-0035), el formato de ESTADO.md y el checklist de cierre de fase.

Luego carga habilidades específicas del stack detectado en PLAN.md o PROYECTO.md:
- Backend Python: `Skill("fastapi-experto")`, `Skill("patrones-python")`
- Frontend Angular: `Skill("angular-moderno")`
- Modelos de datos: `Skill("postgresql-experto")`
- Autenticación: `Skill("auth-patrones")`
- Siempre: `Skill("manejo-errores")`

### Si `--iterative` está activo

Tras cargar `ejecutar-task-iterativo`, sigue el protocolo definido ahí
(loop per-task con Pasos 1-8 internos del skill). El resto de pasos de
este comando se delegan al skill iterativo. Saltar los Pasos 2-7 de este
comando. El Paso 8 (Reporte final) y Reglas de comportamiento siguen
aplicando en ambos modos.

## Paso 1 — Verificación de prerrequisitos

Verifica en orden:
1. `.planning/PROYECTO.md` — debe existir
2. `.planning/fases/0N-PLAN.md` — debe existir. Sin esto: "Ejecuta `/swl:planear-fase N` primero."
3. `.planning/fases/0N-CONTEXTO.md` — debe existir
4. Verifica que el PLAN.md no tenga "[REQUIERE REVISIÓN HUMANA]"
5. **Requirement Freeze**: verifica que el frontmatter del PLAN.md contenga
   `estado: aprobado`. Si contiene `estado: borrador` o no tiene campo `estado`:
   - DETENER ejecución
   - Reportar: "El PLAN.md no está aprobado. Ejecuta `/swl:aprobar-plan N` para
     aprobarlo y firmarlo antes de ejecutar."
   - NO proceder sin aprobación explícita del usuario

6. **Gate G1 — verificación de integridad del plan firmado**: tras confirmar
   `estado: aprobado`, recomputa el hash del PLAN y compáralo contra su lock:
   ```bash
   node -e "const {verificarPlan}=require('./scripts/lib/plan-lock'); console.log(JSON.stringify(verificarPlan('.planning/fases/0N-PLAN.md')))"
   ```
   Interpreta el resultado:
   - `ok: true, modo: "firmado"` → el plan no fue mutado tras su aprobación.
     Continúa con normalidad.
   - `ok: true, modo: "legacy"` → plan aprobado SIN lock (creado antes de la
     Fase 09, cláusula de gracia D-05). Muestra una **advertencia visible** al
     usuario: "Plan en modo legacy (sin firma SHA256). Se ejecuta sin
     verificación de integridad. Para firmarlo: `/swl:aprobar-plan N`." y
     continúa.
   - `ok: false, modo: "mutado"` → **DETENER ejecución**. El plan cambió tras la
     firma. Reporta `hashEsperado` y `hashActual` y di: "El PLAN fue modificado
     después de su aprobación. Revisa los cambios y vuelve a aprobarlo con
     `/swl:aprobar-plan N` antes de ejecutar." NO proceder.
   - `ok: false` con cualquier otro modo (`lock-corrupto`, `sin-firmar`,
     `no-existe`) → DETENER y reportar el `motivo` exacto.

   Repite esta verificación al inicio de cada slice (el plan no debe mutar
   durante la ejecución — Requirement Freeze).

Lee los tres archivos completos. Verifica estado de Git (`git status`, `git log --oneline -5`). Si hay cambios no commiteados, pregunta cómo proceder.

**Nota sobre Requirement Freeze**: una vez que el plan está aprobado y la ejecución
comienza, los slices y tareas del plan son inmutables. Si durante la ejecución se
detecta que el scope necesita cambiar, el agente DEBE pausar y escalar al usuario
en lugar de modificar silenciosamente el alcance. Esto previene el "goal drift"
donde el resultado final diverge del plan acordado.

## Paso 2 — Análisis del PLAN.md

Extrae: lista ordenada de slices con tareas, slices HITL vs AFK, estimación total, comandos de verificación.

Si hay slices HITL, preséntalos ANTES de comenzar:
```
Esta fase tiene [N] decisiones HITL:
HITL 1 — [nombre]: [decisión requerida]
¿Puedes resolverlas ahora, o prefieres que pause antes de cada una?
```

Espera respuesta.

## Paso 3 — Inicio del registro de ejecución

Crea o inicializa `.planning/ESTADO.md` siguiendo el formato definido en el skill (progreso, slices, última acción, próxima acción).

## Paso 4 — Ejecución por slices

Para cada slice del PLAN.md en orden:

### 4.1 — Preparación
Anuncia inicio del slice (nombre, tipo AFK/HITL, número de tareas). Si es HITL no resuelto, pide decisión y espera.

### 4.2 — Delegación al implementador-swl
Delega con instrucción precisa: contexto a leer (PROYECTO.md, PLAN.md, CONTEXTO.md, CLAUDE.md), tareas del slice, criterio de verificación. El skill define las reglas de commit atómico y formato.

**Cota dura del prompt al sub-agente**: ≤30k tokens (intent + constraints + acceptance criteria + file locations). Por encima de esa cifra el sub-agente puede entrar en autocompact thrashing y abortar sin escribir archivos (caso real SIGAF 2026-05-22). Si el prompt necesario excede 30k tokens:

- Dividir el slice en sub-slices más pequeños (<10k tokens de spec cada uno).
- O ejecutar directamente sin delegar si la spec está clara para ti (scope <5 archivos boilerplate similar).

Indicador para optar por trabajo directo: si pasas más de 5 minutos escribiendo specs para preparar la delegación, el costo de delegar supera el ahorro.

Detalle del patrón anti-thrashing en `agentes/orquestador-swl.md` sección "4. Tamaño máximo del prompt al sub-agente".

### 4.3 — Verificación del slice
Ejecuta comandos de verificación del PLAN.md, verifica archivos, revisa commits (`git log --oneline -5`), corre tests. Si falla: máximo 2 reintentos antes de escalar al usuario.

### 4.4 — Actualización del ESTADO.md
Marca slice completado, actualiza contadores, registra desviaciones según las reglas del skill (menor: registrar; moderada: notificar; mayor: STOP).

### 4.5 — Avanzar
Reporta al usuario (1-3 líneas: qué se implementó, commits, tests). Continúa automáticamente (AFK) o espera confirmación (HITL).

## Paso 5 — Manejo de errores

Según tipo de error:
- **Bug de implementación**: el agente lo resuelve. Si no puede en 2 intentos, presenta opciones al usuario.
- **Desviación de la spec**: PARAR. Reportar: qué dice el plan, qué encontró la realidad, opciones.
- **Dependencia faltante**: PARAR. Reportar.

## Paso 6 — RESUMEN.md

Al completar todos los slices, genera `.planning/fases/0N-RESUMEN.md` con: slices implementados (commits, archivos), resultados de tests, desviaciones del plan, decisiones técnicas, deuda técnica, estado final, criterios de aceptación verificados, próximos pasos.

**Anexo propositivo (Fase 13, ADR-0037)**: antes de cerrar, ejecuta el propose-step
sobre el diff de la fase (`node hooks/lib/propose-step.js --rango=<base>..HEAD`) e
incluye una sección "Anexo propositivo" en el RESUMEN.md **solo si hay ≥1 señal** de
adyacencia (auth/PII/pagos, migración de schema). Si no hay señal, omite la sección
(silencio, no sección vacía). El anexo propone, nunca bloquea. Opt-out `SWL_PROPOSE=0`.

## Paso 7 — Actualización de HOJA-RUTA.md y ESTADO.md

Marca fase completada en HOJA-RUTA.md con fecha. Actualiza ESTADO.md con estado general.

**Liberar la fase activa** (gate G0): elimina `.planning/locks/fase-activa.json` —
la fase ya no está en ejecución y `hooks/spec-gate.js` debe volver a advertir si se
escribe código sin una nueva fase aprobada:

```bash
node -e "const fs=require('fs'); const p='.planning/locks/fase-activa.json'; if(fs.existsSync(p)){fs.unlinkSync(p); console.log('fase activa liberada')} else {console.log('sin fase activa que liberar')}"
```

NO eliminar el `.lock` del plan (`0N-PLAN.md.lock`) — ese es evidencia de
aprobación versionada, no runtime.

## Paso 8 — Verificación automática y reporte final

**Verify automático (gate G4)**: tras generar RESUMEN.md y liberar la fase activa,
invoca `/swl:verificar --until-converge` automáticamente — el cierre de fase ya no
es un paso manual recomendado, es parte del flujo.

- Opt-out: si el usuario invocó `/swl:ejecutar-fase N --sin-verify`, omite la
  verificación y registra la desviación en el RESUMEN.md ("verificación diferida
  por --sin-verify — razón: [la que dé el usuario]").
- Si la verificación converge (Señal A): el VERIFICACION.md queda generado y el
  reporte final lo incluye.
- Si NO converge (Señal B/C) o queda abortada: reportar el estado del loop al
  usuario — la fase NO se declara verificada.

```
Fase N — [nombre] completada.

Slices implementados: [N de N]
Commits creados: [N]
Tests pasando: [N de N]
Desviaciones del plan: [N, o "ninguna"]
Verificación: [convergió en pasada K | diferida por --sin-verify | NO convergió — ver detalle]

Archivos generados:
- .planning/fases/0N-RESUMEN.md
- .planning/fases/0N-VERIFICACION.md (verify automático)
- .planning/ESTADO.md (actualizado)
- .planning/HOJA-RUTA.md (actualizado)
```

## Reglas de comportamiento

- NUNCA hagas commits grandes al final — commits atómicos por tarea.
- NUNCA continúes con el siguiente slice si el anterior falló la verificación.
- NUNCA modifiques archivos `.planning/` como parte de los commits de código.
- Si la ejecución se interrumpe, ESTADO.md debe quedar actualizado para que `/swl:checkpoint` pueda retomar.
- Documenta TODAS las desviaciones en el RESUMEN.md.
- Si un criterio de aceptación no se puede cumplir, documenta por qué y escala al usuario.
- NUNCA ejecutes un plan sin `estado: aprobado` — el requirement freeze es obligatorio.
- NUNCA modifiques el scope del plan silenciosamente durante la ejecución.
- Si el agente implementador propone cambios de scope, PARAR y escalar al usuario.
