@saulwade/swl-ses 1.4.2 → 1.5.0

package/habilidades/discutir-fase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: discutir-fase
-description: Cuestionario adaptativo que se ejecuta antes de planear una fase de desarrollo. Extrae decisiones técnicas y de negocio del usuario, clasifica respuestas como "cerradas" (no negociables) o "abiertas" (decisión delegada al agente), y produce un archivo CONTEXTO.md que alimenta al planificador.
-version: "1.0.0"
+description: Cuestionario adaptativo que se ejecuta antes de planear una fase de desarrollo. Extrae decisiones técnicas y de negocio del usuario, clasifica respuestas como "cerradas" (no negociables) o "abiertas" (decisión delegada al agente), y produce un archivo CONTEXTO.md que alimenta al planificador. Inicia con discovery routing (5 paths) que evita el cuestionario completo cuando no aplica.
+version: "1.1.0"
 herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
 exclusiones:
   - "No cargar si el usuario ya tiene un CONTEXTO.md poblado para la fase en curso — ir directo a `planear-fase`."
@@ -35,6 +35,54 @@ antipatrón de planear con suposiciones implícitas que luego se contradicen.
 
 ---
 
+## Paso 0 — Discovery routing (obligatorio antes del cuestionario)
+
+Antes de lanzar el cuestionario adaptativo, ejecuta **scan ligero** de
+`.planning/` para identificar la ruta correcta. Esto evita gastar turnos en
+un cuestionario cuando la petición del usuario no requiere una fase nueva.
+
+Inspirado en `kiro-discovery` (cc-sdd) — ver `temp/cc-sdd-main/tools/cc-sdd/templates/agents/claude-code-skills/skills/kiro-discovery/SKILL.md`.
+
+### Inventario rápido (solo metadata, NO leer contenido completo)
+
+1. `Glob` sobre `.planning/fases/*.md` → lista de fases existentes y su estado.
+2. `Read` de `.planning/HOJA-RUTA.md` (si existe) — para mapear la petición a roadmap.
+3. `Read` del `.planning/ESTADO.md` (si existe) — para conocer fase activa.
+
+Si no hay `.planning/`, marca **proyecto verde** y salta al cuestionario completo (Ruta C por defecto).
+
+### Determinar la ruta
+
+| Ruta | Cuándo aplica | Acción |
+|------|--------------|--------|
+| **RUTA_A** — Extiende fase existente | La petición es una extensión, fix o enhancement dentro del scope de una fase ya planeada. Cabe en `tasks` de un PLAN.md existente. | NO ejecutar cuestionario. Informar al usuario: "Esto encaja en la fase `<N>`. ¿Procedo a actualizar su PLAN.md o lanzar `/swl:ejecutar-fase <N>` directo?" |
+| **RUTA_B** — Sin fase necesaria | Fix trivial (<5 archivos, 1 tarea, sin decisiones de scope). Bug puntual, typo, dependencia, refactor menor. | NO ejecutar cuestionario. Informar al usuario: "Esto no requiere fase formal. Procedo directo con `implementador-swl` o el agente de stack. ¿De acuerdo?" |
+| **RUTA_C** — Nueva fase single-scope | Petición nueva, no encaja en fases existentes, single-domain. | Ejecutar cuestionario completo (Bloques 1-4). |
+| **RUTA_D** — Decomposición multi-fase | Petición spans múltiples dominios o produciría >20 tareas en una sola fase. | Ejecutar cuestionario **resumido** (Bloque 1 + Bloque 4) para extraer decisiones de scope. Luego sugerir descomposición en N fases. Confirmar con usuario antes de proceder. |
+| **RUTA_E** — Mixto | La petición combina: extensión de fase existente + nueva fase + posiblemente fix trivial. | Presentar al usuario la decomposición propuesta y confirmar antes de proceder. Para la parte "nueva fase" ejecutar cuestionario reducido. |
+
+### Heurísticas de matching
+
+- Si la petición menciona explícitamente "fase N" → considerar RUTA_A primero.
+- Si la petición empieza con "arregla", "corrige", "fix", "elimina" → considerar RUTA_B primero.
+- Si la petición empieza con "implementa", "crea", "agrega feature" → RUTA_C o RUTA_D.
+- Si la petición tiene `y`, `,`, `también` enumerando >2 cosas distintas → RUTA_D o RUTA_E.
+
+### Cómo presentar el veredicto
+
+Tras el scan, emite un mensaje corto al usuario antes del cuestionario:
+
+```
+Discovery routing: RUTA_<X>
+Justificación: <una oración explicando por qué>
+Próximo paso: <qué se hará a continuación>
+¿Procedo? [s/N o sugerir otra ruta]
+```
+
+Solo después de confirmar la ruta procede con el cuestionario (si aplica).
+
+---
+
 ## Protocolo de entrevista adaptativa
 
 ### Regla 1 — Máximo 4 preguntas por mensaje

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

@@ -0,0 +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

package/habilidades/protocolo-revision-swl/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: protocolo-revision-swl
+description: >
+  Protocolo de revisión adversarial per-task con git diff como single source of
+  truth. Adapta el patrón task-local review de cc-sdd al ecosistema SWL: los
+  revisores existentes (revisor-codigo-swl, revisor-seguridad-swl, revisor-*-swl)
+  aplican este protocolo cuando trabajan sobre una sola tarea atómica en lugar
+  de una fase completa. Devuelve APPROVED o REJECTED con findings de severidad
+  estructurados y boundary checks. Cargar desde el agente revisor cuando
+  ejecutar-fase corre en modo --iterative (task por task) o cuando se solicita
+  revisión acotada a un commit / patch específico.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep, Glob, Bash]
+exclusiones:
+  - "No cargar para revisión de fase completa multi-archivo — usar el flujo estándar del revisor con `/swl:revisar` y `/swl:verificar`."
+  - "No cargar para auditoría de seguridad profunda — usar `revisor-seguridad-swl` con `checklist-seguridad`."
+  - "No cargar como sustituto de la verificación goal-backward post-ejecución — `verificar-trabajo` cubre eso a nivel de fase."
+  - "No cargar para revisar código que no ha sido staged ni commiteado todavía — el protocolo requiere un diff o set de archivos definido."
+evolvable: true
+---
+
+# Protocolo de revisión per-task
+
+## Propósito
+
+Revisar el resultado de UNA tarea atómica de implementación (no una fase
+completa) con el rigor de un revisor adversarial. El protocolo está diseñado
+para coexistir con los revisores especializados existentes (`revisor-codigo-swl`,
+`revisor-react-swl`, `revisor-typescript-swl`, etc.): esos agentes cargan
+este skill cuando el alcance es task-local en lugar de phase-wide.
+
+Adaptado del patrón `kiro-review` de cc-sdd. Mantiene los principios de
+swl-ses (separación revisor/ejecutor de `reglas/gobernanza.md`, veto items
+y cap enforcement, scoring 9.0+ obligatorio para APPROVED).
+
+## Cuándo cargar
+
+- El orquestador ejecuta `/swl:ejecutar-fase --iterative` y necesita revisión task-por-task
+- Un agente implementador reportó `READY_FOR_REVIEW` para una sub-tarea específica
+- El usuario pide "revisa este último commit" o "revisa lo que acabo de hacer"
+- Tras una remediación de un finding previo y se necesita re-verificación acotada
+
+## Cuándo NO cargar
+
+Ver `exclusiones` en frontmatter.
+
+---
+
+## Inputs requeridos
+
+Antes de empezar, identifica los siguientes inputs. Si falta cualquiera, pide
+clarificación al caller (orquestador o implementador) en lugar de proceder
+con asunciones.
+
+| Input | Forma | Obligatorio |
+|-------|-------|-------------|
+| Task ID | Texto de la tarea desde PLAN.md (ej. "3.2 — Crear endpoint POST /facturas") | Sí |
+| Boundary scope | Lista de paths/módulos que la tarea puede modificar | Sí |
+| Spec references | IDs de requirements y design sections que la tarea satisface | Sí — si existen |
+| Diff | `git diff <base>..HEAD` o set de archivos modificados | Sí |
+| Validation commands | Comandos descubiertos por el caller (test, build, lint, smoke) | Sí — si aplica el stack |
+| Implementer status report | El reporte estructurado del ejecutor (`READY_FOR_REVIEW`, archivos tocados, decisiones) | Recomendado |
+
+---
+
+## Paso 1 — Primera acción obligatoria: `git diff`
+
+Antes de leer cualquier otro archivo, ejecuta:
+
+```bash
+git diff --stat       # alcance del cambio
+git diff <base>..HEAD # contenido real
+```
+
+El reporte del implementador NO es fuente de verdad. El diff sí. Si el diff
+es grande, lee los archivos modificados directamente — no resuamen ni inferas
+desde el reporte del ejecutor.
+
+**Por qué**: el implementador puede honestamente reportar "implementé X" pero
+haber introducido Y como efecto colateral. El diff captura todo, incluido lo
+que el ejecutor no recuerda haber tocado.
+
+---
+
+## Paso 2 — Checks mecánicos (resultado = señal primaria)
+
+Estos checks son determinísticos y producen evidencia directa. Aplica TODOS
+antes de pasar a interpretación.
+
+### Check 1: Regression safety
+
+Corre la suite de tests del proyecto con las `validation_commands` provistas.
+Ejemplo:
+
+```bash
+npm test               # o pytest, o cargo test, etc.
+```
+
+- **Tests pasan** → continuar.
+- **Tests fallan** → `REJECTED` inmediato. Incluye el conteo y nombres de tests fallidos en el reporte.
+- **Tests skipped aumentan vs base** → riesgo de regresión silenciosa (regla `monitor-ci.md`). Reportar el delta como finding de severidad MAJOR.
+
+### Check 2: Sin marcadores placeholder nuevos
+
+```bash
+git diff <base>..HEAD | grep -E "\+.*\b(TBD|TODO|FIXME|HACK|XXX)\b" || true
+```
+
+Marcadores nuevos solo se aceptan con justificación explícita en el reporte
+del implementador asociada al PLAN.md vigente (referencia a task ID, no texto suelto).
+Sin justificación → finding MAYOR.
+
+### Check 3: Sin secretos hardcodeados
+
+```bash
+git diff <base>..HEAD | grep -E "(api[_-]?key|password|secret|token)\s*[=:]\s*[\"'][^\"'\s]{8,}[\"']" -i || true
+```
+
+Cualquier match → `REJECTED` con finding CRÍTICO. Aplica los patrones
+documentados en `reglas/seguridad-agentes.md` § "Protección de secretos".
+
+### Check 4: Boundary violations
+
+Lista de archivos modificados:
+
+```bash
+git diff --name-only <base>..HEAD
+```
+
+Cada archivo modificado DEBE estar dentro del `boundary scope` declarado en
+la tarea. Si un archivo fuera del boundary aparece modificado:
+
+- Si es modificación trivial (formateo, comentario) → finding MENOR.
+- Si es modificación funcional → finding MAYOR. La tarea debe declarar el
+  boundary extendido o el cambio se devuelve al implementador para extraer
+  a una tarea aparte.
+
+---
+
+## Paso 3 — Verificación de alineación con spec
+
+Lee directamente:
+
+- El texto de la tarea en `PLAN.md` (no parafrases — copia literal).
+- Los requirements citados en el campo `requirements` de la tarea.
+- Las secciones de design citadas si existen.
+
+Para cada requirement/design ref, verifica:
+
+| Pregunta | Cómo verificar |
+|----------|----------------|
+| ¿El código implementa lo que el requirement dice? | Mapear líneas concretas del diff al texto del requirement |
+| ¿Falta algo del requirement que el código no cubre? | Listar gaps específicos |
+| ¿Hay código fuera del scope del requirement? | Comparar con design — si no está justificado, es scope creep |
+
+Si hay gap de cobertura → finding MAYOR con cita del requirement y línea
+faltante en el diff.
+
+---
+
+## Paso 4 — Veto items (heredados del revisor base)
+
+Los revisores SWL existentes declaran sus propios veto items (ver
+`reglas/gobernanza.md` § "Veto items y cap enforcement"). Cuando este
+protocolo se carga desde uno de ellos, los veto items del revisor padre
+aplican íntegros.
+
+**Si detectas CUALQUIER veto item**:
+
+- Score CAP automático a 6.0/10.
+- Verdict pasa a `REJECTED` independientemente de qué tan limpio esté el resto.
+- 2+ veto items → cap a 3.0/10.
+
+Lista de veto items del revisor padre debe estar disponible en su SKILL/agente.
+Si no se puede determinar, reporta `MANUAL_VERIFY_REQUIRED` en lugar de inventar.
+
+---
+
+## Paso 5 — Emitir veredicto estructurado
+
+### Formato del reporte
+
+```json
+{
+  "protocol": "protocolo-revision-swl",
+  "task_id": "3.2 — Crear endpoint POST /facturas",
+  "verdict": "APPROVED | REJECTED",
+  "score": 9.2,
+  "score_cap_applied": null,
+  "mechanical_checks": {
+    "regression_safety": "PASS",
+    "no_new_placeholders": "PASS",
+    "no_hardcoded_secrets": "PASS",
+    "boundary_respected": "PASS | VIOLATIONS_FOUND"
+  },
+  "spec_alignment": {
+    "requirements_covered": ["R-12", "R-13"],
+    "requirements_gap": [],
+    "design_drift": "NONE | SLIGHT | SIGNIFICANT"
+  },
+  "veto_items": [],
+  "findings": [
+    {
+      "severity": "CRITICAL | MAJOR | MINOR",
+      "file": "app/api/facturas.py:42",
+      "issue": "Descripción breve",
+      "remediation": "Qué cambiar y cómo"
+    }
+  ],
+  "summary": "Una oración resumiendo el veredicto y la razón principal.",
+  "next_action": "MERGE | FIX_AND_RE_REVIEW | ESCALATE_TO_HUMAN"
+}
+```
+
+### Reglas de scoring (compatibles con `checklist-calidad`)
+
+- `APPROVED` requiere `score >= 9.0` Y `veto_items.length === 0` Y todos los
+  mechanical_checks en PASS.
+- Severidad MAJOR baja el score 1.0 punto cada una.
+- Severidad MINOR baja 0.3 puntos cada una.
+- Severidad CRITICAL → automaticamente `REJECTED` (score irrelevante).
+- 1 veto item → cap a 6.0. 2+ veto items → cap a 3.0.
+
+### Reglas del `next_action`
+
+- `MERGE`: APPROVED — el caller (orquestador) puede commitear y avanzar a la siguiente tarea.
+- `FIX_AND_RE_REVIEW`: REJECTED con findings MAYORES — el implementador aplica remediation, se vuelve a invocar este protocolo. Máximo 2 ciclos antes de escalar.
+- `ESCALATE_TO_HUMAN`: 2 ciclos de FIX no convergieron, O hay CRÍTICO sin remediación clara, O hay decisión de scope ambigua. Activa el `notificador-swl` si está configurado.
+
+---
+
+## Persistencia del veredicto
+
+El veredicto JSON se persiste en:
+
+```
+.planning/audit/reviews/<task-id>-<timestamp>.json
+```
+
+Esto permite que `auto-evolucion-swl` y `/swl:metricas` calculen tasas de
+APPROVED vs REJECTED por agente revisor y por tipo de tarea — datos
+necesarios para identificar revisores con calibración floja o tipos de
+tarea sistemáticamente problemáticos.
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Confiar en el reporte del implementador como source of truth**: el primer paso obligatorio es `git diff`. Saltarse esto y derivar el veredicto del status report del implementador deja pasar bugs colaterales no reportados. Causa: optimización falsa para ahorrar tokens. Solución: `git diff --stat` siempre antes de cualquier interpretación.
+- **Boundary violation reportada como MENOR sin verificar funcionalidad**: el revisor ve que se modificó un archivo fuera del boundary y lo marca MENOR porque "se ve pequeño". Causa: no se inspeccionó qué hace el cambio. Solución: para CUALQUIER archivo fuera del boundary, abrir el cambio y clasificar trivial vs funcional antes de asignar severidad.
+- **Tests skipped tratados como tests pasados**: el conteo de tests verde no distingue entre pasados y saltados. Causa: parsing superficial del output del runner. Solución: comparar `skipped` count vs base — si aumenta sin causa documentada en el diff, es regresión silenciosa (regla `monitor-ci.md`).
+- **APPROVED con score < 9.0 "porque la tarea era pequeña"**: el revisor reduce el umbral subjetivamente. Causa: ceder a presión de entrega. Solución: la regla es 9.0 estricto; tareas pequeñas que no llegan a 9.0 indican findings que valen MENOR o MAYOR — emitir como findings y devolver al implementador.
+- **Veto items ignorados porque "el resto está limpio"**: el cap de score es no-negociable. Causa: el revisor pondera "promedio" de calidad. Solución: 1 veto item = score capped automáticamente, sin compensación posible desde otras dimensiones.
+
+---
+
+## Relación con otros componentes SWL
+
+| Componente | Relación |
+|-----------|----------|
+| `revisor-codigo-swl` y revisores de lenguaje | Cargan este skill cuando trabajan task-local en lugar de phase-wide |
+| `ejecutar-task-iterativo` (Sub-fase 4) | Invoca este protocolo después de cada implementer dispatch en modo `--iterative` |
+| `verificar-trabajo` | Complementario — verificar-trabajo es goal-backward post-fase; este protocolo es task-local post-implementación |
+| `reglas/gobernanza.md` | Veto items + cap enforcement heredados |
+| `checklist-calidad` | Score >=9.0 unificado |
+| `auto-evolucion-swl` | Consume los veredictos persistidos para detectar revisores descalibrados |
+
+## Checklist de cierre del protocolo
+
+- [ ] `git diff --stat` ejecutado y diff leído antes de cualquier interpretación
+- [ ] 4 mechanical checks ejecutados (regression, placeholders, secretos, boundary)
+- [ ] Alineación con spec verificada citando IDs concretos
+- [ ] Veto items del revisor padre evaluados
+- [ ] Score calculado y cap aplicado si corresponde
+- [ ] Veredicto JSON persistido en `.planning/audit/reviews/`
+- [ ] `next_action` claro (MERGE / FIX_AND_RE_REVIEW / ESCALATE_TO_HUMAN)