@saulwade/swl-ses 2.4.2 → 2.5.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/estructura-proyecto-claude/SKILL.md

@@ -8,7 +8,7 @@ description: >
   hooks, plugins), o configurar MCP. Cubre arquitectura de 4 capas, jerarquía
   de memoria, 6 tipos de extensión, 30 hook events, frontmatter de skills/agents/commands
   y settings avanzados.
-version: "1.1.0"
+version: "1.1.1"
 herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
 exclusiones:
   - "No cargar para iniciar un proyecto desde cero — ese flujo usa `/swl:nuevo-proyecto` que incluye entrevista de contexto antes de generar la estructura; este skill genera estructura pero no recoge requisitos de negocio."
@@ -150,7 +150,16 @@ y orden de resolución en
 
 ---
 
-## 7 secciones obligatorias de CLAUDE.md
+## 7 secciones de CLAUDE.md (contrato completo)
+
+> **Reconciliación de contratos**: el auditor síncrono (`auditar-claudemd.js`,
+> vía `/swl:claudemd audit`) exige como mínimo 4 secciones (Stack, Comandos,
+> Code style, Conventions). Las 7 de esta tabla son el contrato COMPLETO al que
+> un proyecto maduro converge. En un proyecto recién inicializado, Security /
+> Testing / Git Workflow se agregan solo cuando el cuestionario de
+> `nuevo-proyecto` capturó contenido real para ellas — empezar compacto es la
+> best practice oficial; secciones genéricas sin política del proyecto son
+> relleno.
 
 | # | Sección | Contenido |
 |---|---------|-----------|

package/habilidades/harness-claude-code/SKILL.md

@@ -10,7 +10,7 @@ description: >
   Cargar cuando el usuario reporte "se acabó la cuota", se prepare una
   sesión Opus larga (>2h), se planifique adopción de MCP servers, o se
   detecte context-rot recurrente.
-version: "1.0.3"
+version: "1.0.4"
 evolved: false
 herramientasPermitidas: [Read]
 exclusiones:
@@ -266,6 +266,8 @@ Sin observar la métrica, no puedes optimizarla.
 
 ## Gotchas / Errores comunes no obvios
 
+- **Matriz de canales de hooks — stderr con exit 0 es un canal INVISIBLE** [origen: check-update 2026-07-08, el aviso de nuevas versiones se emitió al vacío desde su creación]: en Claude Code, el canal correcto depende del exit code. **exit 0 (éxito)**: solo el stdout llega — como contexto del turno en UserPromptSubmit/SessionStart (o `hookSpecificOutput.additionalContext`); el stderr no lo lee nadie. **exit 2 (bloqueo)**: solo el stderr llega al modelo con la razón del bloqueo; stdout con exit 2 = bloqueo ciego (regla ya conocida, L1 #4 de APRENDIZAJES). Anti-patrón resultante: "hook que funciona perfecto y nadie ve" — todo aviso al usuario desde un hook exitoso DEBE ir a stdout, idealmente con instrucción explícita ("INFORMA AL USUARIO...") para que el modelo lo retransmita. Verificación: correr el hook a mano con un flag de forzado y confirmar en qué canal aparece el mensaje.
+
 - **El payload de los hooks PostToolUse NO trae `model` ni `usage` — pero `transcript_path` SÍ viene y contiene ambos**: un hook que necesite el contexto real o el modelo activo no debe estimarlos por heurística (un contador de invocaciones × tokens promedio divergió >2x del contexto real y nunca se corregía tras `/compact` — caso swl-ses 2026-07-03). Fuente exacta: leer la cola del JSONL de `transcript_path`, tomar el último mensaje `type: 'assistant'` del hilo principal (filtrar `isSidechain: true` — los subagentes tienen OTRO context window) y sumar `usage.input_tokens + cache_read_input_tokens + cache_creation_input_tokens` = tamaño exacto del contexto de esa llamada; `message.model` da el modelo real. Tras `/compact` la siguiente entrada refleja el contexto compactado — la medición se auto-corrige sin resets.
 - **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1` aplicado por default a todos los proyectos**: causa truncado de contexto en sesiones que sí requieren 1M (análisis masivo de codebase, refactor cross-module). Causa: tomar la recomendación del artículo como universal. Solución: aplicar SOLO en proyectos donde se observe context bloat real. Para análisis profundos, dejar el default 1M.
 - **Sub-agentes Sonnet/Haiku que delegan al padre Opus pidiendo "más razonamiento"**: el padre acaba haciendo el trabajo que se quería offloadear. Causa: spec del sub-agente vaga. Solución: el padre debe hacer una spec clara con criterios de aceptación; sub-agentes solo escalan si encuentran tradeoff arquitectónico explícito, no por dificultad genérica.

package/habilidades/instalar-sistema/SKILL.md

@@ -2,7 +2,7 @@
 name: instalar-sistema
 description: "Instala o actualiza el sistema SWL en el proyecto actual. Usar PROACTIVAMENTE cuando: (1) el usuario pide instalar SWL, (2) se detecta que el proyecto no tiene .claude/agents/ ni .claude/skills/ con componentes SWL, (3) el usuario menciona perfiles de instalación o pide agregar agentes/skills al proyecto. NO usar cuando SWL ya está instalado y funcionando correctamente."
 user-invocable: false
-version: "1.0.1"
+version: "1.0.2"
 herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
 exclusiones:
   - "No cargar si SWL ya está instalado y funcionando (`doctor` pasa sin errores); no reinstalar para resolver problemas de uso del sistema."
@@ -176,6 +176,8 @@ cat .claude/settings.json 2>/dev/null | grep -c "hooks/"
 
 ## Gotchas / Errores comunes no obvios
 
+- **Un generador de archivos de instrucciones NUNCA sobrescribe un archivo sin su marcador de procedencia** [caso real 2026-07-08: `install --target opencode` pisó el AGENTS.md canónico del repo madre — 420 líneas de documentación curada reemplazadas por el stub del transformador]: la rama "clásica" de `generarArchivoInstrucciones` escribía a ciegas. Regla: antes de sobrescribir AGENTS.md/GEMINI.md/etc. en el destino, verificar que el archivo existente contenga el marcador `Generado por swl-ses`; sin marcador = contenido del usuario o doc canónica del proyecto → preservar y avisar ("borra el archivo y reinstala si quieres el generado"). El guard vive en `scripts/instalador.js` (rama clásica). Patrón general: todo writer de archivos compartidos necesita prueba de ownership antes de escribir — el mismo principio del merge-no-overwrite (ADR-0040) aplicado a archivos generados.
+
 - **Instalación con perfil `completo` en proyecto Python/TypeScript instala reglas de lenguaje innecesarias**: si no se usa la detección automática de stack, el perfil `completo` instala 5 reglas Java + 5 Go + 5 Rust aunque el proyecto no use esos lenguajes, incrementando el contexto base en ~700 líneas por sesión. Causa: no se activó la detección automática de stack. Solución: dejar que el instalador detecte automáticamente o usar `--all-langs` solo si se trabaja con todos los lenguajes; verificar con `ls .claude/rules/` post-instalación.
 - **`~/.npmrc` sin el token configurado bloquea la instalación silenciosamente**: `npx @saulwade/swl-ses@latest init` falla con `401 Unauthorized` desde GitHub Packages. Causa: el token de GitHub Packages no está en `~/.npmrc`. Solución: configurar el `_authToken` en `~/.npmrc` y verificar con `npm whoami --registry https://npm.pkg.github.com` antes de la primera instalación.
 - **Cambio de perfil sin `--force` no actualiza componentes existentes**: el usuario cambia de `backend-python` a `fullstack-python-angular` pero los nuevos skills de Angular no se instalan porque los archivos ya existen. Causa: el instalador no sobreescribe por defecto. Solución: usar `--force` explícitamente en cambios de perfil: `install --target claude --profile <nuevo-perfil> --force`.