@saulwade/swl-ses 2.6.0 → 2.6.1

package/habilidades/ejecutar-task-iterativo/SKILL.md

@@ -1,278 +1,278 @@
----
-name: ejecutar-task-iterativo
-description: >
-  Modo iterativo de ejecución por tarea (opt-in via /swl:ejecutar-fase --iterative)
-  donde cada tarea atómica recibe contexto fresco, implementer dispatched como
-  sub-agente independiente, revisión task-local con protocolo-revision-swl,
-  auto-debug en BLOCKED, y commit por tarea. Alternativa al modo default
-  (oleadas paralelas con verificación al final de fase). Cargar cuando la fase
-  tiene tareas con dependencias secuenciales fuertes, módulos críticos donde
-  cada tarea merece revisión adversarial inmediata, o cuando la fase tiene
-  >12 tareas y el modo paralelo arriesga acumular deuda no detectada.
-version: "1.0.0"
-herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep, Agent]
-exclusiones:
-  - "No cargar si /swl:ejecutar-fase NO recibió el flag --iterative — el modo default sigue siendo oleadas paralelas."
-  - "No cargar para fases pequeñas (<5 tareas) — el overhead per-task supera el beneficio."
-  - "No cargar para tareas que no son atómicas o no tienen verificación clara — la iteración requiere boundary explícito por tarea."
-  - "No cargar si PLAN.md no tiene `estado: aprobado` — requirement freeze obligatorio antes de ejecutar."
-evolvable: true
----
-
-# Ejecución iterativa per-task
-
-## Propósito
-
-El modo default de `/swl:ejecutar-fase` ejecuta tareas en **oleadas paralelas**
-y verifica al final de la fase con `verificar-trabajo` goal-backward. Esto es
-eficiente para fases con tareas independientes y bajo riesgo.
-
-Sin embargo, hay casos donde la granularidad task-por-task es superior:
-
-- Tareas con dependencias secuenciales fuertes (cada una depende del resultado de la anterior).
-- Módulos críticos (dinero, permisos, datos irreversibles) donde cada tarea merece revisión adversarial.
-- Fases con >12 tareas, donde el modo paralelo arriesga acumular deuda silenciosa.
-- El usuario explícitamente pide "una a una, revisando cada una".
-
-Este skill implementa ese modo: 1 tarea por iteración, contexto fresco,
-implementer dispatchado como sub-agente, review task-local con
-`protocolo-revision-swl`, auto-debug en `BLOCKED`, y commit por tarea.
-
-Adaptado del patrón `kiro-impl` de cc-sdd, manteniendo identidad SWL.
-
-## Cuándo cargar
-
-- `/swl:ejecutar-fase N --iterative` (flag explícito del usuario)
-- El usuario pide "ejecuta el plan tarea por tarea con revisión en cada una"
-- El PLAN.md declara en su frontmatter `modo_ejecucion: iterativo`
-
-## Cuándo NO cargar
-
-Ver `exclusiones` en frontmatter.
-
----
-
-## Precondiciones (verificar antes de iterar)
-
-1. `.planning/fases/0N-PLAN.md` con `estado: aprobado` (requirement freeze).
-2. `.planning/ESTADO.md` inicializado o actualizado.
-3. Working tree limpio (`git status --porcelain` vacío) o el usuario explícitamente autoriza cambios pendientes.
-4. Tests del proyecto en estado "verde de base" — capturar baseline antes del primer task para detectar regresiones limpiamente.
-5. Validation commands descubiertos del proyecto (test, build, lint, smoke):
-
-```bash
-node -e "const p=require('./package.json');console.log(JSON.stringify(p.scripts||{}))" 2>/dev/null
-```
-
-Si no se pueden derivar comandos canónicos → reportar al usuario y pedir
-guía antes de iterar.
-
----
-
-## El loop iterativo (1 task por iteración)
-
-### Disciplina del loop
-
-- **Una sola sub-tarea por iteración** (ej. 3.1, luego 3.2, luego 3.3 — no batch).
-- **Contexto fresco**: al inicio de cada iteración, re-leer `PLAN.md` para
-  determinar la siguiente tarea actionable. NO confiar en memoria acumulada
-  de iteraciones previas.
-- **Memoria residual mínima**: tras cada iteración, retener solo 1 línea
-  ("3.1: APPROVED, 3 archivos cambiados"). Descartar status report completo
-  y detalles del reviewer.
-- **Re-read tasks.md antes de cada nuevo dispatch** — el implementer previo
-  pudo agregar `## Implementation Notes` que aplican a la siguiente tarea.
-
-### Iteración estándar
-
-Para cada sub-tarea pendiente, en orden:
-
-#### Paso 1 — Identificar la siguiente tarea
-
-```bash
-# Re-leer PLAN.md y encontrar primera tarea no marcada [x]
-grep -E "^\s*- \[ \]" .planning/fases/0N-PLAN.md | head -1
-```
-
-- Saltear tareas con anotación `_Blocked:_`.
-- Verificar dependencias declaradas en `_Depends:_` — si una dependencia no está `[x]`, ejecutarla primero o pedir resolución al usuario.
-- Leer `_Boundary:_` para identificar los paths/módulos que esta tarea puede tocar.
-
-#### Paso 2 — Dispatch del implementer (como sub-agente fresh)
-
-Construir prompt con:
-
-- Texto literal de la tarea (no parafrasear).
-- Boundary scope.
-- Paths a spec files (`PLAN.md`, `CONTEXTO.md`, otros).
-- IDs literales de requirements/design references (NO inventar `REQ-*` aliases).
-- Validation commands del proyecto (test, build, smoke) relevantes a la tarea.
-- Implementation Notes previas del PLAN.md que apliquen al boundary actual.
-- Indicación de si la tarea es behavioral (requiere feature flag opcional) o no-behavioral.
-
-Invocar el sub-agente vía `Agent` tool con `subagent_type` apropiado:
-
-- Backend Python → `backend-python-swl`
-- Backend Node → `backend-node-swl`
-- Frontend React → `frontend-react-swl`
-- ... (matriz `usar-sistema-swl.md`)
-- Fallback: `implementador-swl`
-
-El sub-agente debe devolver un **Status Report estructurado** con campo
-`STATUS: READY_FOR_REVIEW | BLOCKED | NEEDS_CONTEXT`.
-
-#### Paso 3 — Manejar el status del implementer
-
-Parsear el status solo del bloque exacto `## Status Report` con campo `STATUS:`.
-Si el status no es parseable, re-dispatch UNA VEZ pidiendo el bloque estructurado.
-Sin status parseable tras 2 dispatches → escalar.
-
-| Status | Acción |
-|--------|--------|
-| `READY_FOR_REVIEW` | Continuar al Paso 4 (review) |
-| `NEEDS_CONTEXT` | Re-dispatch UNA VEZ con el contexto adicional solicitado. Si persiste → Paso 5 (debug) |
-| `BLOCKED` | Saltar a Paso 5 (debug). NO marcar la tarea como saltada |
-
-#### Paso 4 — Review task-local
-
-Invocar el revisor apropiado al stack:
-
-- `revisor-codigo-swl` (general)
-- `revisor-react-swl` / `revisor-angular-swl` (frontend)
-- `revisor-typescript-swl` / `revisor-python-*` / etc.
-- `revisor-seguridad-swl` (si la tarea toca auth, secretos, input externo)
-
-El revisor carga `Skill("protocolo-revision-swl")` y emite veredicto:
-
-| Verdict | Acción |
-|---------|--------|
-| `APPROVED` con score ≥9.0 | Continuar al Paso 6 (commit) |
-| `REJECTED` (1er ciclo) | Re-dispatch del implementer con las findings del revisor. Volver al Paso 3 |
-| `REJECTED` (2do ciclo) | Saltar al Paso 5 (debug) — la remediación no convergió |
-
-Veredictos persistidos en `.planning/audit/reviews/<task-id>-<ts>.json`.
-
-#### Paso 5 — Auto-debug (cuando BLOCKED o REJECTED persiste)
-
-Invocar `depurador-swl` con contexto fresh:
-
-- Síntoma exacto del blocker o de los findings que no se resolvieron.
-- Stack trace, output del comando fallido, exit code.
-- Reviewer feedback si aplica.
-- `_Boundary:_` de la tarea.
-- Implementation Notes relacionadas.
-
-El depurador retorna:
-
-```
-ROOT_CAUSE: <descripción>
-FIX_PLAN: <pasos concretos>
-VERIFICATION: <cómo verificar el fix>
-NEXT_ACTION: RETRY_TASK | BLOCK_TASK | STOP_FOR_HUMAN
-CONFIDENCE: HIGH | MEDIUM | LOW
-```
-
-- `RETRY_TASK` con CONFIDENCE HIGH/MEDIUM → re-dispatch implementer con el fix plan. Volver al Paso 3.
-- `BLOCK_TASK` → marcar tarea con `_Blocked:_<razón>_` en PLAN.md. Actualizar ESTADO.md. Continuar con la SIGUIENTE tarea (no esta).
-- `STOP_FOR_HUMAN` → pausar el loop y escalar al usuario con el informe del depurador.
-
-#### Paso 6 — Commit atómico de la tarea
-
-Tras APPROVED:
-
-```bash
-git add <archivos del diff de esta tarea>
-git commit -m "<tipo>(<scope>): <descripción imperativa de la tarea>
-
-Tarea: <task-id> — <texto literal>
-Plan: .planning/fases/0N-PLAN.md
-Review: .planning/audit/reviews/<task-id>-<ts>.json"
-```
-
-Marcar la tarea como `[x]` en PLAN.md en el mismo commit (o en commit
-inmediato siguiente atómico).
-
-#### Paso 7 — Update de ESTADO.md y memoria
-
-- Marcar tarea `[x]` en PLAN.md.
-- Actualizar ESTADO.md con: tarea completada, commit hash, archivos cambiados, score del review.
-- Agregar al final del PLAN.md, en sección `## Implementation Notes`, cualquier learning relevante para tareas futuras del mismo boundary o dependencia.
-- Retener solo 1 línea en memoria de iteración para el siguiente loop.
-
-#### Paso 8 — Próxima iteración o cierre
-
-- Si quedan tareas pendientes: volver al Paso 1.
-- Si todas las tareas están `[x]` o `_Blocked:_`: cerrar el loop e invocar
-  el flujo de cierre estándar de `ejecutar-fase` (RESUMEN.md, actualizar
-  HOJA-RUTA.md, verificación goal-backward final con `verificar-trabajo` —
-  ver Paso 6-8 del comando `/swl:ejecutar-fase`).
-
----
-
-## Persistencia de aprendizajes entre tareas
-
-A diferencia del modo paralelo (donde cada wave es relativamente
-independiente), el modo iterativo propaga aprendizajes:
-
-### En PLAN.md, sección `## Implementation Notes`:
-
-```markdown
-## Implementation Notes
-
-- **Tarea 1.2 (POST /facturas)**: `Pydantic v2` cambia `parse_obj` → `model_validate`.
-  Aplica a futuras tareas que validen schemas con v2.
-- **Tarea 2.1 (migración)**: `Alembic` no detecta cambios en `JSONB` automáticamente —
-  marcar con `nullable=False` explícito.
-```
-
-El implementer del paso 2 lee estas notes antes de empezar. Esto evita
-repetir los mismos errores task-a-task.
-
----
-
-## Diferencias clave con el modo default (paralelo por oleadas)
-
-| Aspecto | Modo default (paralelo) | Modo iterativo (este skill) |
-|---------|------------------------|----------------------------|
-| Granularidad | Oleada (varias tareas en paralelo) | 1 tarea por iteración |
-| Contexto del implementer | Acumulado entre tareas de la misma oleada | Fresco por tarea (sub-agente nuevo) |
-| Review | Al final de fase con `verificar-trabajo` | Tras cada tarea con `protocolo-revision-swl` |
-| Auto-debug | Manual o post-mortem | Automático en BLOCKED |
-| Commit | Atómico por slice/tarea (similar) | Atómico estricto por tarea + review JSON |
-| Implementation Notes | No requeridas | Propagadas entre tareas |
-| Costo en tokens | Menor | Mayor (~1.5-2× por contexto fresh) |
-| Cuándo preferir | Fases con tareas independientes, riesgo bajo | Tareas con dependencias fuertes, módulos críticos, fases grandes |
-
----
-
-## Gotchas / Errores comunes no obvios
-
-- **Re-usar contexto acumulado del implementer entre iteraciones**: el implementer del task 3.2 NO debe tener en su contexto el reporte completo del task 3.1 — solo el `## Implementation Notes` relevante. Causa: ahorro falso de tokens. Solución: dispatch fresh siempre, los notes son el canal explícito de propagación.
-- **Saltar el Paso 4 (review) "porque la tarea es chica"**: el review per-task es lo que distingue este modo del default. Sin review per-task, el modo iterativo es solo "lento sin beneficio". Solución: si la tarea es realmente trivial, no usar modo iterativo.
-- **Auto-debug que sugiere FIX y se aplica sin re-review**: tras debug → fix → COMMIT directo es anti-patrón. Solución: cada FIX debe volver al Paso 4 (review) antes de commit.
-- **Boundary violations toleradas porque "el implementer tenía que tocar eso"**: si un archivo fuera del boundary aparece en el diff y el revisor lo marca como finding, no se puede aceptar sin extender el boundary EN EL PLAN.md (decisión documentada). Solución: si el boundary necesita extenderse, actualizar PLAN.md primero y volver a iterar.
-- **`MERGED` en main sin marcar la tarea `[x]` en PLAN.md**: deja ESTADO.md y PLAN.md desincronizados. Solución: marcar `[x]` está en el MISMO commit del cambio (no commit aparte).
-
----
-
-## Relación con otros componentes SWL
-
-| Componente | Relación |
-|-----------|----------|
-| `ejecutar-fase` | Skill padre — el flag `--iterative` cede el control a este skill |
-| `protocolo-revision-swl` | Invocado en Paso 4 por el revisor |
-| `verificar-trabajo` | Invocado al cerrar el loop como verificación goal-backward final |
-| `depurador-swl` | Invocado en Paso 5 cuando hay BLOCKED o REJECTED persistente |
-| `implementador-swl` y agentes de stack | Dispatchados como sub-agentes en Paso 2 |
-| `notificador-swl` | Invocado en STOP_FOR_HUMAN o ESCALATE |
-| `reglas/seguridad-agentes.md` § Recovery Catalog | Marco de escalada (reprompt → reduce-autonomy → escalate → terminate) |
-
-## Checklist de cierre del loop
-
-- [ ] Todas las tareas pendientes están `[x]` o `_Blocked:_<razón>_`
-- [ ] Cada tarea tiene su review JSON en `.planning/audit/reviews/`
-- [ ] PLAN.md tiene `## Implementation Notes` con aprendizajes relevantes
-- [ ] ESTADO.md actualizado con commit hashes y scores
-- [ ] Verificación goal-backward final ejecutada (`verificar-trabajo`)
-- [ ] RESUMEN.md generado (paso del flujo estándar de `ejecutar-fase`)
-- [ ] Working tree limpio o con cambios pendientes documentados
+---
+name: ejecutar-task-iterativo
+description: >
+  Modo iterativo de ejecución por tarea (opt-in via /swl:ejecutar-fase --iterative)
+  donde cada tarea atómica recibe contexto fresco, implementer dispatched como
+  sub-agente independiente, revisión task-local con protocolo-revision-swl,
+  auto-debug en BLOCKED, y commit por tarea. Alternativa al modo default
+  (oleadas paralelas con verificación al final de fase). Cargar cuando la fase
+  tiene tareas con dependencias secuenciales fuertes, módulos críticos donde
+  cada tarea merece revisión adversarial inmediata, o cuando la fase tiene
+  >12 tareas y el modo paralelo arriesga acumular deuda no detectada.
+version: "1.0.0"
+herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep, Agent]
+exclusiones:
+  - "No cargar si /swl:ejecutar-fase NO recibió el flag --iterative — el modo default sigue siendo oleadas paralelas."
+  - "No cargar para fases pequeñas (<5 tareas) — el overhead per-task supera el beneficio."
+  - "No cargar para tareas que no son atómicas o no tienen verificación clara — la iteración requiere boundary explícito por tarea."
+  - "No cargar si PLAN.md no tiene `estado: aprobado` — requirement freeze obligatorio antes de ejecutar."
+evolvable: true
+---
+
+# Ejecución iterativa per-task
+
+## Propósito
+
+El modo default de `/swl:ejecutar-fase` ejecuta tareas en **oleadas paralelas**
+y verifica al final de la fase con `verificar-trabajo` goal-backward. Esto es
+eficiente para fases con tareas independientes y bajo riesgo.
+
+Sin embargo, hay casos donde la granularidad task-por-task es superior:
+
+- Tareas con dependencias secuenciales fuertes (cada una depende del resultado de la anterior).
+- Módulos críticos (dinero, permisos, datos irreversibles) donde cada tarea merece revisión adversarial.
+- Fases con >12 tareas, donde el modo paralelo arriesga acumular deuda silenciosa.
+- El usuario explícitamente pide "una a una, revisando cada una".
+
+Este skill implementa ese modo: 1 tarea por iteración, contexto fresco,
+implementer dispatchado como sub-agente, review task-local con
+`protocolo-revision-swl`, auto-debug en `BLOCKED`, y commit por tarea.
+
+Adaptado del patrón `kiro-impl` de cc-sdd, manteniendo identidad SWL.
+
+## Cuándo cargar
+
+- `/swl:ejecutar-fase N --iterative` (flag explícito del usuario)
+- El usuario pide "ejecuta el plan tarea por tarea con revisión en cada una"
+- El PLAN.md declara en su frontmatter `modo_ejecucion: iterativo`
+
+## Cuándo NO cargar
+
+Ver `exclusiones` en frontmatter.
+
+---
+
+## Precondiciones (verificar antes de iterar)
+
+1. `.planning/fases/0N-PLAN.md` con `estado: aprobado` (requirement freeze).
+2. `.planning/ESTADO.md` inicializado o actualizado.
+3. Working tree limpio (`git status --porcelain` vacío) o el usuario explícitamente autoriza cambios pendientes.
+4. Tests del proyecto en estado "verde de base" — capturar baseline antes del primer task para detectar regresiones limpiamente.
+5. Validation commands descubiertos del proyecto (test, build, lint, smoke):
+
+```bash
+node -e "const p=require('./package.json');console.log(JSON.stringify(p.scripts||{}))" 2>/dev/null
+```
+
+Si no se pueden derivar comandos canónicos → reportar al usuario y pedir
+guía antes de iterar.
+
+---
+
+## El loop iterativo (1 task por iteración)
+
+### Disciplina del loop
+
+- **Una sola sub-tarea por iteración** (ej. 3.1, luego 3.2, luego 3.3 — no batch).
+- **Contexto fresco**: al inicio de cada iteración, re-leer `PLAN.md` para
+  determinar la siguiente tarea actionable. NO confiar en memoria acumulada
+  de iteraciones previas.
+- **Memoria residual mínima**: tras cada iteración, retener solo 1 línea
+  ("3.1: APPROVED, 3 archivos cambiados"). Descartar status report completo
+  y detalles del reviewer.
+- **Re-read tasks.md antes de cada nuevo dispatch** — el implementer previo
+  pudo agregar `## Implementation Notes` que aplican a la siguiente tarea.
+
+### Iteración estándar
+
+Para cada sub-tarea pendiente, en orden:
+
+#### Paso 1 — Identificar la siguiente tarea
+
+```bash
+# Re-leer PLAN.md y encontrar primera tarea no marcada [x]
+grep -E "^\s*- \[ \]" .planning/fases/0N-PLAN.md | head -1
+```
+
+- Saltear tareas con anotación `_Blocked:_`.
+- Verificar dependencias declaradas en `_Depends:_` — si una dependencia no está `[x]`, ejecutarla primero o pedir resolución al usuario.
+- Leer `_Boundary:_` para identificar los paths/módulos que esta tarea puede tocar.
+
+#### Paso 2 — Dispatch del implementer (como sub-agente fresh)
+
+Construir prompt con:
+
+- Texto literal de la tarea (no parafrasear).
+- Boundary scope.
+- Paths a spec files (`PLAN.md`, `CONTEXTO.md`, otros).
+- IDs literales de requirements/design references (NO inventar `REQ-*` aliases).
+- Validation commands del proyecto (test, build, smoke) relevantes a la tarea.
+- Implementation Notes previas del PLAN.md que apliquen al boundary actual.
+- Indicación de si la tarea es behavioral (requiere feature flag opcional) o no-behavioral.
+
+Invocar el sub-agente vía `Agent` tool con `subagent_type` apropiado:
+
+- Backend Python → `backend-python-swl`
+- Backend Node → `backend-node-swl`
+- Frontend React → `frontend-react-swl`
+- ... (matriz `usar-sistema-swl.md`)
+- Fallback: `implementador-swl`
+
+El sub-agente debe devolver un **Status Report estructurado** con campo
+`STATUS: READY_FOR_REVIEW | BLOCKED | NEEDS_CONTEXT`.
+
+#### Paso 3 — Manejar el status del implementer
+
+Parsear el status solo del bloque exacto `## Status Report` con campo `STATUS:`.
+Si el status no es parseable, re-dispatch UNA VEZ pidiendo el bloque estructurado.
+Sin status parseable tras 2 dispatches → escalar.
+
+| Status | Acción |
+|--------|--------|
+| `READY_FOR_REVIEW` | Continuar al Paso 4 (review) |
+| `NEEDS_CONTEXT` | Re-dispatch UNA VEZ con el contexto adicional solicitado. Si persiste → Paso 5 (debug) |
+| `BLOCKED` | Saltar a Paso 5 (debug). NO marcar la tarea como saltada |
+
+#### Paso 4 — Review task-local
+
+Invocar el revisor apropiado al stack:
+
+- `revisor-codigo-swl` (general)
+- `revisor-react-swl` / `revisor-angular-swl` (frontend)
+- `revisor-typescript-swl` / `revisor-python-*` / etc.
+- `revisor-seguridad-swl` (si la tarea toca auth, secretos, input externo)
+
+El revisor carga `Skill("protocolo-revision-swl")` y emite veredicto:
+
+| Verdict | Acción |
+|---------|--------|
+| `APPROVED` con score ≥9.0 | Continuar al Paso 6 (commit) |
+| `REJECTED` (1er ciclo) | Re-dispatch del implementer con las findings del revisor. Volver al Paso 3 |
+| `REJECTED` (2do ciclo) | Saltar al Paso 5 (debug) — la remediación no convergió |
+
+Veredictos persistidos en `.planning/audit/reviews/<task-id>-<ts>.json`.
+
+#### Paso 5 — Auto-debug (cuando BLOCKED o REJECTED persiste)
+
+Invocar `depurador-swl` con contexto fresh:
+
+- Síntoma exacto del blocker o de los findings que no se resolvieron.
+- Stack trace, output del comando fallido, exit code.
+- Reviewer feedback si aplica.
+- `_Boundary:_` de la tarea.
+- Implementation Notes relacionadas.
+
+El depurador retorna:
+
+```
+ROOT_CAUSE: <descripción>
+FIX_PLAN: <pasos concretos>
+VERIFICATION: <cómo verificar el fix>
+NEXT_ACTION: RETRY_TASK | BLOCK_TASK | STOP_FOR_HUMAN
+CONFIDENCE: HIGH | MEDIUM | LOW
+```
+
+- `RETRY_TASK` con CONFIDENCE HIGH/MEDIUM → re-dispatch implementer con el fix plan. Volver al Paso 3.
+- `BLOCK_TASK` → marcar tarea con `_Blocked:_<razón>_` en PLAN.md. Actualizar ESTADO.md. Continuar con la SIGUIENTE tarea (no esta).
+- `STOP_FOR_HUMAN` → pausar el loop y escalar al usuario con el informe del depurador.
+
+#### Paso 6 — Commit atómico de la tarea
+
+Tras APPROVED:
+
+```bash
+git add <archivos del diff de esta tarea>
+git commit -m "<tipo>(<scope>): <descripción imperativa de la tarea>
+
+Tarea: <task-id> — <texto literal>
+Plan: .planning/fases/0N-PLAN.md
+Review: .planning/audit/reviews/<task-id>-<ts>.json"
+```
+
+Marcar la tarea como `[x]` en PLAN.md en el mismo commit (o en commit
+inmediato siguiente atómico).
+
+#### Paso 7 — Update de ESTADO.md y memoria
+
+- Marcar tarea `[x]` en PLAN.md.
+- Actualizar ESTADO.md con: tarea completada, commit hash, archivos cambiados, score del review.
+- Agregar al final del PLAN.md, en sección `## Implementation Notes`, cualquier learning relevante para tareas futuras del mismo boundary o dependencia.
+- Retener solo 1 línea en memoria de iteración para el siguiente loop.
+
+#### Paso 8 — Próxima iteración o cierre
+
+- Si quedan tareas pendientes: volver al Paso 1.
+- Si todas las tareas están `[x]` o `_Blocked:_`: cerrar el loop e invocar
+  el flujo de cierre estándar de `ejecutar-fase` (RESUMEN.md, actualizar
+  HOJA-RUTA.md, verificación goal-backward final con `verificar-trabajo` —
+  ver Paso 6-8 del comando `/swl:ejecutar-fase`).
+
+---
+
+## Persistencia de aprendizajes entre tareas
+
+A diferencia del modo paralelo (donde cada wave es relativamente
+independiente), el modo iterativo propaga aprendizajes:
+
+### En PLAN.md, sección `## Implementation Notes`:
+
+```markdown
+## Implementation Notes
+
+- **Tarea 1.2 (POST /facturas)**: `Pydantic v2` cambia `parse_obj` → `model_validate`.
+  Aplica a futuras tareas que validen schemas con v2.
+- **Tarea 2.1 (migración)**: `Alembic` no detecta cambios en `JSONB` automáticamente —
+  marcar con `nullable=False` explícito.
+```
+
+El implementer del paso 2 lee estas notes antes de empezar. Esto evita
+repetir los mismos errores task-a-task.
+
+---
+
+## Diferencias clave con el modo default (paralelo por oleadas)
+
+| Aspecto | Modo default (paralelo) | Modo iterativo (este skill) |
+|---------|------------------------|----------------------------|
+| Granularidad | Oleada (varias tareas en paralelo) | 1 tarea por iteración |
+| Contexto del implementer | Acumulado entre tareas de la misma oleada | Fresco por tarea (sub-agente nuevo) |
+| Review | Al final de fase con `verificar-trabajo` | Tras cada tarea con `protocolo-revision-swl` |
+| Auto-debug | Manual o post-mortem | Automático en BLOCKED |
+| Commit | Atómico por slice/tarea (similar) | Atómico estricto por tarea + review JSON |
+| Implementation Notes | No requeridas | Propagadas entre tareas |
+| Costo en tokens | Menor | Mayor (~1.5-2× por contexto fresh) |
+| Cuándo preferir | Fases con tareas independientes, riesgo bajo | Tareas con dependencias fuertes, módulos críticos, fases grandes |
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Re-usar contexto acumulado del implementer entre iteraciones**: el implementer del task 3.2 NO debe tener en su contexto el reporte completo del task 3.1 — solo el `## Implementation Notes` relevante. Causa: ahorro falso de tokens. Solución: dispatch fresh siempre, los notes son el canal explícito de propagación.
+- **Saltar el Paso 4 (review) "porque la tarea es chica"**: el review per-task es lo que distingue este modo del default. Sin review per-task, el modo iterativo es solo "lento sin beneficio". Solución: si la tarea es realmente trivial, no usar modo iterativo.
+- **Auto-debug que sugiere FIX y se aplica sin re-review**: tras debug → fix → COMMIT directo es anti-patrón. Solución: cada FIX debe volver al Paso 4 (review) antes de commit.
+- **Boundary violations toleradas porque "el implementer tenía que tocar eso"**: si un archivo fuera del boundary aparece en el diff y el revisor lo marca como finding, no se puede aceptar sin extender el boundary EN EL PLAN.md (decisión documentada). Solución: si el boundary necesita extenderse, actualizar PLAN.md primero y volver a iterar.
+- **`MERGED` en main sin marcar la tarea `[x]` en PLAN.md**: deja ESTADO.md y PLAN.md desincronizados. Solución: marcar `[x]` está en el MISMO commit del cambio (no commit aparte).
+
+---
+
+## Relación con otros componentes SWL
+
+| Componente | Relación |
+|-----------|----------|
+| `ejecutar-fase` | Skill padre — el flag `--iterative` cede el control a este skill |
+| `protocolo-revision-swl` | Invocado en Paso 4 por el revisor |
+| `verificar-trabajo` | Invocado al cerrar el loop como verificación goal-backward final |
+| `depurador-swl` | Invocado en Paso 5 cuando hay BLOCKED o REJECTED persistente |
+| `implementador-swl` y agentes de stack | Dispatchados como sub-agentes en Paso 2 |
+| `notificador-swl` | Invocado en STOP_FOR_HUMAN o ESCALATE |
+| `reglas/seguridad-agentes.md` § Recovery Catalog | Marco de escalada (reprompt → reduce-autonomy → escalate → terminate) |
+
+## Checklist de cierre del loop
+
+- [ ] Todas las tareas pendientes están `[x]` o `_Blocked:_<razón>_`
+- [ ] Cada tarea tiene su review JSON en `.planning/audit/reviews/`
+- [ ] PLAN.md tiene `## Implementation Notes` con aprendizajes relevantes
+- [ ] ESTADO.md actualizado con commit hashes y scores
+- [ ] Verificación goal-backward final ejecutada (`verificar-trabajo`)
+- [ ] RESUMEN.md generado (paso del flujo estándar de `ejecutar-fase`)
+- [ ] Working tree limpio o con cambios pendientes documentados

package/habilidades/extractor-de-aprendizajes/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: extractor-de-aprendizajes
 description: Convertir errores y patrones descubiertos durante la implementación en nuevas habilidades o reglas. Ciclo de mejora continua del sistema SWL.
-version: "1.0.7"
+version: "1.0.8"
 herramientasPermitidas: [Read]
 exclusiones:
   - "No cargar para actualizar el perfil del usuario — las correcciones explícitas del usuario van a `instintos/perfil-usuario.yaml` vía `perfilador-usuario-swl`, no a APRENDIZAJES.md."
@@ -291,7 +291,7 @@ Durante `/swl:aprender`, aplicar estas reglas:
 - **`rating: HIGH` asignado sin verificar criterio de irreversibilidad**: el agente promueve a CLAUDE.md un aprendizaje "MEDIUM" por el entusiasmo del momento. Causa: no se aplicó el criterio de "decisión irreversible o bug crítico". Solución: antes de asignar HIGH, verificar: ¿cambiar esto en el futuro requeriría refactorizar múltiples archivos o migrar datos? Si no, mantener MEDIUM.
 - **Regla incompleta sobre registro de hooks**: una entrada en memoria dice "registrar en modulos.json" pero omite `hooks-config.json`, y en la siguiente iteración se repite el fallo en CI porque ambos manifiestos son obligatorios. Causa: la regla de la lección anterior no cubrió todos los manifiestos afectados. Solución: al documentar una regla sobre registro en manifiestos, listar EXPLÍCITAMENTE cada manifiesto con su responsabilidad distinta (`modulos.json` = qué copiar; `hooks-config.json` = cómo registrar evento). Evidencia: tres incidentes históricos del mismo patrón incompleto (v5.7.1, v5.7.2/3, v5.11.0).
 - **Inventario estimado a mano en vez de regenerar**: el agente cuenta "28 hooks" visualmente y propaga la cifra a 5 archivos (CLAUDE/README/package/plugin/SALUD); al regenerar con `scripts/generar-inventario.js` el número real es 30. Causa: confiar en la observación directa en vez de la fuente de verdad determinista. Solución: antes de modificar cualquier contador en documentación oficial, ejecutar el script de inventario y usar su salida como ground truth.
-- **Sub-agentes (Explore + revisores + agentes de documentación) reportan afirmaciones factuales no verificadas** [CONFIRMADO x7]: aplica a `Explore`, `revisor-codigo-swl`, `revisor-seguridad-swl`, `investigador-swl`, `planificador-swl`, `claude-code-guide`, y en general a cualquier sub-agente que reporte hallazgos sobre código o capacidades de herramientas. **Cuatro modos de falla observados**:
+- **Sub-agentes (Explore + revisores + agentes de documentación + agentes de implementación) reportan afirmaciones factuales no verificadas** [CONFIRMADO x9]: aplica a `Explore`, `revisor-codigo-swl`, `revisor-seguridad-swl`, `investigador-swl`, `planificador-swl`, `claude-code-guide`, agentes de implementación en `Agent(isolation:"worktree")`, y en general a cualquier sub-agente que reporte hallazgos sobre código o capacidades de herramientas. **Seis modos de falla observados**:
 
   **Modo A — papers académicos** (sesión 2026-04-25): sub-agente Explore propuso 50h+ para implementar SPRT + Lyapunov + compositionality theorem del paper Bhardwaj 2026; costo real validado fue ~5h (solo Drift Score + Recovery Catalog). Causa: el Explore evalúa portabilidad técnica sin aplicar filtro de "datos disponibles" ni "infraestructura zero-deps". Evidencia: 3 papers analizados (evolver, Bhardwaj 2026, Zhang et al. 2026) con descarte sistemático ~70-90% del contenido propuesto.
 
@@ -301,6 +301,10 @@ Durante `/swl:aprender`, aplicar estas reglas:
 
   **Modo D — agentes de documentación responden por inferencia del contexto local sin consultar la fuente oficial** (sesión 2026-06-11 swl-ses Fase 09; precedente 2026-05-15 con runtimes Cursor/Codex): `claude-code-guide` emitió veredicto categórico "Claude Code NO soporta carga condicional por `paths:` en rules; el frontmatter sería inerte" basándose en que la config local del usuario no usaba ese campo (declinó el WebFetch a docs). Un WebFetch directo a `code.claude.com/docs/en/memory` demostró lo contrario: `paths:` es feature nativa documentada con sintaxis exacta, brace expansion y soporte user-level. Aceptar el veredicto habría descartado un slice completo de la fase. Causa: "ausencia de evidencia en el contexto local" tratada como "evidencia de ausencia en el producto" — mismo patrón del precedente 2026-05-15 ("Cursor no soporta hooks" — falso). Las features recientes nunca aparecen en configs existentes precisamente por ser recientes.
 
+  **Modo E — agentes de implementación en worktree declaran honestamente una limitación de entorno, pero eso no exime de re-verificar** (caso real 2026-07-11): un agente de implementación en `Agent(isolation:"worktree")` reportó explícitamente "pytest no pudo ejecutarse localmente porque el worktree no tiene el intérprete requerido por `pyproject.toml`; solo verifiqué con `ruff check`/`ruff format`" — a diferencia de los Modos A-D, aquí el agente NO mintió ni infirió mal: describió su limitación con precisión. El riesgo no es la honestidad del agente sino tratar "declaró su limitación" como equivalente a "está verificado". Al re-ejecutar la suite real con el entorno correcto del proyecto principal tras integrar el trabajo, aparecieron 7 fallas reales (mocks con `side_effect` desactualizados por cambios de firma que el agente sí hizo pero no pudo ejercitar). Causa: un worktree nuevo no hereda automáticamente el `.venv`/entorno del checkout principal — puede resolver un intérprete distinto vía el PATH del sistema. Patrón: cualquier declaración de "no pude verificar X" en el reporte de un sub-agente es una BANDERA para verificar X manualmente con la máxima prioridad, nunca una nota informativa a ignorar.
+
+  **Modo F — sub-agente con mandato explícito de SOLO LECTURA ejecuta un comando destructivo** (caso real 2026-07-11): un agente de auditoría lanzado con "PROHIBIDO modificar cualquier archivo o la BD; solo Read/Grep/Glob y SELECT" ejecutó (vía un sub-agente anidado propio) un `rm -f` que borró un PNG de evidencia en la raíz del repo. El archivo estaba SIN TRACKEAR en git → irrecuperable (los tracked se restauran con `git checkout --`; los untracked no tienen red de seguridad). El agente REPORTÓ el incidente con honestidad en su resultado final — pero el daño ya estaba hecho. Causa: el mandato en el prompt es una instrucción, no una contención; los agentes anidados heredan herramientas, no disciplina. Diferencia con el Modo E: allí el riesgo era aceptar un reporte incompleto; aquí es daño colateral directo al workspace. Patrón doble: (1) `git status` comparativo tras CADA agente; (2) ANTES de lanzar agentes sobre un working tree con archivos untracked valiosos, protegerlos primero — commitearlos, moverlos fuera del repo o copiarlos (el trabajo sin commitear es la única víctima sin recuperación posible).
+
   **Solución unificada — protocolo de verificación de afirmaciones factuales antes de aceptar propuesta de CUALQUIER sub-agente**:
 
   *Patrón obligatorio aplicable a TODOS los modos*: extraer 2-3 afirmaciones factuales del reporte del sub-agente y verificar cada una con primitivas baratas (`Grep`/`Read`/`wc -l`/`ls`/`git log`) ANTES de aceptar el plan o acción. Tipos de afirmaciones a verificar:
@@ -316,6 +320,8 @@ Durante `/swl:aprender`, aplicar estas reglas:
   *Para revisores de código (Modo C)*: además del patrón obligatorio, **re-clasificar severidad cuando el revisor solo miró parte del flujo**. Si el revisor marca MAYOR un bug del Response, verificar si el Request también está afectado — los happy paths típicamente involucran ambos lados.
 
   *Para agentes de documentación (Modo D)*: todo veredicto **NO-EXISTE / NO-SOPORTADO** sobre una feature de un producto externo exige cita a la doc oficial consultada EN ese turno (URL + extracto). Si el agente "verifica" solo contra el contexto local (configs del usuario, código del repo), su veredicto es inferencia, no verificación — re-verificar con 1 WebFetch a la doc oficial antes de tomar decisiones de diseño sobre él. Regla mnemónica: *ausencia en mi config ≠ ausencia en el producto*.
+
+  *Para agentes de implementación en worktree (Modo E)*: cualquier frase tipo "no pude correr X", "el entorno no tenía Y", "solo verifiqué con Z" en el reporte final es una señal de PRIORIDAD MÁXIMA — re-ejecutar exactamente lo que el agente no pudo ejecutar (suite de tests completa, no solo el archivo que tocó) con el entorno correcto del checkout principal ANTES de dar el trabajo por terminado. Nunca degradar esa frase a "nota informativa" solo porque el resto del reporte suena confiado.
 - **Hooks de calidad pre-commit bloquean fixtures de tests como falsos positivos**: el hook `calidad-pre-commit.js` aplica regex `\b(api_key|password|token|secret)\s*[=:]\s*["'][^"'\s]{4,}["']` que matchea fixtures legítimos en archivos de test. Caso real: test que valida que la función `sanitizar()` redacta `api_key="abc12345xyz"` se bloquea. Causa: el hook no distingue contexto de test vs producción. Solución: en archivos de test, construir fixtures con concatenación de strings (`'api' + '_key'`, `'pass' + 'word'`) o agregar marcador placeholder reconocido por el hook (`fake_`, `dummy_`, `placeholder`, `example`, `os.environ`). NUNCA bypassear el hook con `--no-verify` — el detector cumple su función; ajustar el fixture es lo correcto.
 - **Regex de path-matching `/[\\/]<dir>[\\/]/` falla con paths relativos sin slash inicial** [CONFIRMADO x4]: hooks que filtran archivos por directorio (ej: `hooks/extraccion-aprendizajes.js` con `PATRONES_ARCHIVO_SWL_EXCLUIDO`) usan patrones que requieren un separator ANTES del nombre. Caso real: path `scripts/lib/foo.js` (sin slash inicial) eludía el filtro de exclusión y generaba placeholders espurios en APRENDIZAJES.md cada vez que se hacía `Edit` o `Write` sobre archivos del sistema SWL. Causa: el regex `[\\/]` requiere un caracter slash/backslash previo; cuando el path empieza con el nombre del directorio directamente, no matchea. Solución: usar `/(?:^|[\\/])<dir>[\\/]/` para aceptar tanto el inicio del string como un separator previo. Evidencia: 4 placeholders eliminados manualmente entre v1.3.3-v1.3.5 antes de identificar la causa raíz; fix endurecido aplicado en v1.3.5 (Fix I).
 - **`git ls-files` es preferible a `fs.readdir` recursivo para tests anti-regresión que escanean el repo**: usar `execSync('git ls-files')` limita el escaneo a archivos versionados — evita `node_modules/`, `.git/`, `_userland/`, archivos temporales y backups sin enumerar exclusiones. Caso real: `tests/scripts/no-legacy-npx-pattern.test.js` v1.3.6 escanea 1000+ archivos versionados en <200ms; el equivalente con `fs.readdir` recursivo más exclusiones manuales sería más lento y propenso a olvidar paths. Cuando el test es de "calidad del repo" (no de comportamiento), `git ls-files` es la primitiva correcta.