@saulwade/swl-ses 2.4.2 → 2.5.1

package/comandos/swl/nuevo-proyecto.md

@@ -89,9 +89,24 @@ Espera confirmación ("sí", "correcto", "adelante") o correcciones. Si hay corr
 Una vez confirmado el resumen, delega la investigación del stack al agente `investigador-swl`:
 
 - Instrucción al agente: investigar el stack tecnológico elegido, sus versiones estables actuales, patrones recomendados, y generar el directorio `research/` dentro de `.planning/`.
-- El agente debe producir al menos: `research/STACK.md`, `research/PATRONES.md`, `research/RIESGOS.md`.
+- El agente debe producir al menos: `research/STACK.md`, `research/PATRONES.md`, `research/RIESGOS.md`. Estos archivos NO tienen plantilla en `plantillas/research/` — el investigador los genera desde cero (las plantillas `ARQUITECTURA/FUNCIONALIDADES/RESUMEN/TRAMPAS` son del flujo de adopción, donde hay código que mapear).
 - Mientras el agente investiga, tú avanzas con la creación de los archivos de planeación base (Paso 5).
 
+### Paso 4b — PRD y ADRs iniciales (opcional, proyectos no triviales)
+
+Si el proyecto tiene ≥3 fases estimadas, dominio regulado (pregunta 14) o
+integraciones externas complejas, ofrecer al usuario ANTES de generar la
+planeación base:
+
+- **`producto-prd-swl`** → PRD formal (historias de usuario, criterios de
+  aceptación de negocio, MoSCoW) que enriquece REQUISITOS.md.
+- **`arquitecto-swl`** → ADRs iniciales en `.planning/adrs/` (elección de
+  stack, arquitectura de módulos, decisiones difíciles de revertir) + índice
+  `README.md` con estados.
+
+Para proyectos simples (1-2 fases, CRUD, sin regulación), saltar este paso —
+la ceremonia no compensa (`Skill("prevencion-sobreingenieria")`).
+
 ## Paso 5 — Creación de archivos de planeación
 
 Crea el directorio `.planning/` con la siguiente estructura:
@@ -101,7 +116,9 @@ Crea el directorio `.planning/` con la siguiente estructura:
 ├── PROYECTO.md
 ├── REQUISITOS.md
 ├── HOJA-RUTA.md
+├── ESTADO.md
 ├── fases/
+├── adrs/          (si corrió el Paso 4b)
 └── research/
 ```
 
@@ -135,6 +152,25 @@ Estructura:
 - Si el usuario no definió fases claras, propón una división lógica basada en las respuestas del Bloque C
 - Estado inicial de todas las fases: "Pendiente"
 
+### .planning/ESTADO.md
+
+Poblarlo desde la entrevista (NUNCA dejarlo como plantilla vacía — la plantilla
+de `swl-ses init` es solo el esqueleto):
+- Fase actual: "Ninguna — proyecto inicializado, siguiente paso `/swl:discutir-fase 1`"
+- Prioridad declarada (pregunta 11), deadline (pregunta 10)
+- Bloqueos conocidos y puntos `[POR DEFINIR]` de la entrevista
+
+### Paso 5b — Control de versiones
+
+Con la respuesta de la pregunta 15:
+
+1. Si el directorio NO es un repo git: `git init -b main`.
+2. Si no existe `.gitignore`: generarlo según el stack elegido, incluyendo
+   SIEMPRE `.env`, `.env.*`, `.claude/settings.local.json` y los dirs de
+   artefactos del stack (`node_modules/`, `__pycache__/`, `dist/`, etc.).
+3. Commit inicial de la planeación (`chore: inicializar proyecto con planeación SWL`)
+   SOLO si el usuario confirmó usar git — nunca commitear sin preguntar.
+
 ## Paso 6 — Generar CLAUDE.md inicial del proyecto
 
 Si NO existe `CLAUDE.md` en la raíz del proyecto, generarlo con la estructura
@@ -180,14 +216,29 @@ de continuar.
 
 Detalle del contrato cruzado en `@docs/contrato-aprender-claudemd.md`.
 
-## Paso 7 — Reporte al usuario
+## Paso 7 — Checklist de arranque (ejecutable, no informativo)
+
+Antes de reportar, verifica cada ítem y corrige lo que falle (Fase 4 del
+skill `nuevo-proyecto` — este paso la hace obligatoria en el comando):
+
+- [ ] Ningún `[TBD]`/`[POR DEFINIR]` en ítems críticos (nombre, problema, funcionalidad core) — los no críticos pueden quedar documentados
+- [ ] Cada requisito funcional tiene etiqueta de prioridad
+- [ ] Cada fase de HOJA-RUTA.md tiene objetivo medible y criterio de éxito
+- [ ] ESTADO.md poblado (no plantilla vacía)
+- [ ] CLAUDE.md auditado con veredicto OK (Paso 6)
+- [ ] Git inicializado y `.gitignore` presente (si el usuario eligió git)
+
+## Paso 8 — Reporte al usuario
 
 Al terminar, reporta:
 
 1. Lista de archivos creados con sus rutas absolutas (incluyendo CLAUDE.md
    si se generó o se modificó)
 2. Resumen de la investigación del agente (cuando esté disponible)
-3. Próximo paso recomendado: "Para comenzar a trabajar en la Fase 1, usa `/swl:discutir-fase 1`"
+3. Próximos pasos recomendados:
+   - "Para comenzar a trabajar en la Fase 1, usa `/swl:discutir-fase 1`"
+   - Si el repo vive (o vivirá) en GitHub: "`/swl:configurar-ci init` instala
+     los pipelines de CI y seguridad (lint, tests, review con Claude en PRs)"
 4. Si encontraste riesgos o ambigüedades durante la entrevista, listarlos aquí como "Puntos a resolver"
 
 ## Reglas de comportamiento

package/comandos/swl/predecir.md

@@ -8,8 +8,10 @@ description: >
   acuerdo. Usar antes de /swl:planear-fase en fases de riesgo, antes de un
   refactor grande, o cuando el costo de descubrir un problema DESPUÉS de
   implementar es alto. Con --adversarial usa el set atacante (Rompedor,
-  Tramposo, Escalador, Novato, Insider).
-argument-hint: "[descripción del cambio] [--scope <glob>] [--adversarial] [--presupuesto N] [--chain planear-fase]"
+  Tramposo, Escalador, Novato, Insider). Con --abogado-diablo delega al agente
+  abogado-diablo-swl una crítica profunda de la decisión (pre-mortem +
+  doubt-driven review) cuyo dictamen puede ser NO PROCEDER.
+argument-hint: "[descripción del cambio] [--scope <glob>] [--adversarial] [--abogado-diablo] [--presupuesto N] [--chain planear-fase]"
 allowed-tools: [Read, Grep, Glob, Bash, Write, Agent, Skill]
 ---
 
@@ -42,6 +44,7 @@ propuesta, el debate compara varias).
 [descripción]          La propuesta de cambio a analizar (obligatoria; si falta, preguntar)
 --scope <glob>         Archivos relevantes para grounding (default: derivar del texto)
 --adversarial          Set de personas atacantes en vez del set default
+--abogado-diablo       Crítica profunda de la decisión (agente abogado-diablo-swl) en vez del panel
 --presupuesto N        Máximo de hallazgos totales (default: 40 → 8 por persona)
 --chain planear-fase   Al terminar, ofrecer arrancar /swl:planear-fase con los hallazgos como contexto
 ```
@@ -120,6 +123,33 @@ Personas: [set] | Hallazgos brutos: N | Tras dedup: M
 [PROCEDER | PROCEDER CON AJUSTES (lista) | REPLANTEAR (razón)]
 ```
 
+## Modo `--abogado-diablo` — crítica de la decisión, no del cambio
+
+El panel de personas **asume que el cambio se hará** y enumera problemas de
+implementación. Cuando la duda es anterior — *¿deberíamos hacer esto?* — el
+modo abogado del diablo reemplaza los Pasos 2-3 por UNA invocación profunda:
+
+```
+Agent(abogado-diablo-swl) con:
+- La propuesta + el paquete de conocimiento del Paso 1
+- Instrucción: ejecutar su protocolo completo (pre-mortem ×2-3 +
+  doubt-driven review + steelman) y emitir dictamen
+```
+
+Diferencias con el panel:
+
+| | Panel (default/adversarial) | `--abogado-diablo` |
+|---|---|---|
+| Pregunta que responde | "¿Qué problemas causará este cambio?" | "¿Deberíamos hacer este cambio?" |
+| Veredicto posible | PROCEDER / AJUSTES / REPLANTEAR | PROCEDER / CON CONDICIONES / **NO PROCEDER** |
+| Técnica | 5 perspectivas en frío + anti-herd | Pre-mortem + alternativas descartadas + contraevidencia + trigger de reversión |
+| Profundidad | Amplitud (5 ángulos, ~8 hallazgos c/u) | Profundidad (1 crítica exhaustiva de la decisión) |
+
+El Paso 4 (persistencia y reporte) aplica igual — el dictamen se persiste en el
+mismo directorio de handoff con `tipo: 'predecir-abogado-diablo'`. Combinable
+en secuencia: primero `--abogado-diablo` (¿hacerlo?); si el dictamen es
+PROCEDER, corrida normal del panel (¿qué cuidar al hacerlo?).
+
 ## Paso 5 — Encadenamiento (si `--chain planear-fase`)
 
 Ofrecer arrancar `/swl:planear-fase` indicando el directorio del handoff. El

package/comandos/swl/seguridad.md

@@ -0,0 +1,189 @@
+---
+name: swl:seguridad
+description: >
+  Chequeo de seguridad del PROYECTO COMPLETO (no del diff): escaneo de secretos
+  en el repo, auditoría de dependencias con CVEs, revisión OWASP dirigida a los
+  módulos críticos vía revisor-seguridad-swl, verificación de gates de seguridad
+  del pipeline CI, y detección de superficie LLM (prompt injection) cuando
+  aplica. Consolida todo en un reporte de postura de seguridad con score, veto
+  items y acciones priorizadas. Usar al adoptar un proyecto, antes de un release
+  mayor, tras un incidente, o periódicamente. Para revisar solo los cambios de
+  una fase usar /swl:verificar --solo-seguridad; para el diff usar /swl:revisar
+  seguridad.
+argument-hint: "[--rapido] [--threat-model] [--llm] [--json]"
+allowed-tools: [Read, Grep, Glob, Bash, Write, Agent, Skill]
+---
+
+# /swl:seguridad — Postura de seguridad del proyecto completo
+
+Eres el coordinador de un chequeo de seguridad integral. A diferencia de
+`/swl:verificar` (que audita el diff de una fase) y de `/swl:revisar seguridad`
+(que revisa cambios recientes), este comando evalúa la **postura del proyecto
+entero**: secretos, dependencias, código, pipeline y superficie LLM.
+
+## Cuándo usar
+
+- Al adoptar un proyecto existente (complemento natural de `/swl:adoptar-proyecto`).
+- Antes de un release mayor o del primer despliegue productivo.
+- Tras un incidente de seguridad o la rotación de un secreto filtrado.
+- Periódicamente (candidato a `/swl:cron` mensual).
+
+**Cuándo NO usar**: para el diff de una fase (→ `/swl:verificar
+--solo-seguridad`), para revisar un PR (→ `/swl:revisar seguridad`), o para
+auditar artefactos de skills/plugins antes de instalarlos (→
+`Skill("seguridad-skills-ia")`).
+
+## Flags
+
+```
+--rapido        Solo capas 1-2 (secretos + dependencias). ~2 minutos.
+--threat-model  Añade la capa 6: genera/actualiza THREAT-MODEL.md con Skill("threat-model-lite").
+--llm           Fuerza la capa 5 (ai-runtime-security) aunque la detección automática no encuentre stack LLM.
+--json          Además del reporte Markdown, emite el resumen como JSON (para CI).
+```
+
+## Paso 0 — Carga y alcance
+
+```
+Skill("checklist-seguridad")
+```
+
+Detectar el stack (lockfiles, extensiones dominantes) y enumerar los módulos
+críticos del proyecto: auth/, endpoints/rutas públicas, manejo de archivos,
+pagos, todo lo que toque datos de usuario. Si existe `.planning/`, revisar
+reportes previos de este comando en `.planning/audit/` para comparar postura.
+
+## Capa 1 — Secretos en el repositorio
+
+Escaneo del repo completo (tracked files + historial reciente), no solo del
+working tree:
+
+```bash
+# Working tree — patrones de credenciales (mismas familias que el hook escaneo-secretos)
+git grep -nIE "(sk-(ant|proj|live|test)-|AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{36}|glpat-|xox[baprs]-|-----BEGIN (RSA|EC|OPENSSH) PRIVATE KEY-----)" -- . ':!*.lock' ':!node_modules'
+# Claves genéricas asignadas
+git grep -nIE "(password|passwd|secret|api[_-]?key|token)\s*[=:]\s*['\"][^'\"]{8,}['\"]" -- '*.py' '*.js' '*.ts' '*.env*' '*.yaml' '*.yml' '*.json' ':!*test*' ':!*spec*'
+# Historial: archivos .env commiteados alguna vez
+git log --all --diff-filter=A --name-only --pretty=format: -- '*.env' '.env.*' | sort -u
+```
+
+Si `gitleaks` está instalado, preferirlo (`gitleaks detect --no-banner`) —
+cubre historial completo con menos falsos positivos. Complemento del sistema:
+el audit-tool `pentest-scanner.js` y el hook `escaneo-secretos.js` (mismas
+familias de patrones) están disponibles cuando swl-ses está instalado; el flujo
+`/swl:verificar --full` los orquesta sobre el diff.
+
+**Todo hallazgo de secreto en historial es CRÍTICO aunque ya esté rotado o
+gitignoreado** — sigue el protocolo Hallazgo A/B/C de
+`arreglar-al-detectar.md` (limpiar historial es operación destructiva →
+Hallazgo C, decisión del usuario).
+
+## Capa 2 — Dependencias (supply chain)
+
+```
+Skill("dependencias-auditoria")
+```
+
+Ejecutar el auditor del ecosistema detectado (`npm audit` / `pip-audit` /
+`cargo audit` / `govulncheck` / `composer audit` / `mvn dependency-check`).
+Reglas de severidad de `reglas/seguridad.md`: CVE crítico → 72 horas, medio →
+2 semanas. Registrar también: dependencias abandonadas (>18 meses sin release)
+y pins abiertos (`^`, `>=`, `*`) en producción.
+
+## Capa 3 — Código (OWASP, proyecto completo dirigido)
+
+Delegar a `revisor-seguridad-swl` vía Agent con alcance de proyecto:
+
+```
+Agent(revisor-seguridad-swl) con:
+- Alcance: los módulos críticos del Paso 0 (no un diff)
+- Instrucción: auditoría OWASP Top 10 + path traversal + CSRF con severidad
+  CVSSv3 y veto items. Priorizar auth/autz, validación de entradas, queries,
+  manejo de archivos y sanitización de salida. Cargar Skill("checklist-seguridad")
+  y Skill("auth-patrones") / Skill("iam-secretos") según lo que encuentre.
+```
+
+En proyectos grandes (>500 archivos), dividir en 2-3 invocaciones por dominio
+(auth, API pública, manejo de datos) y consolidar.
+
+## Capa 4 — Pipeline CI (gates de seguridad)
+
+```
+Skill("devsecops-pipeline-security")
+```
+
+Verificar contra los 5 gates del skill qué existe en `.github/workflows/` (o
+equivalente GitLab/Azure): secret scanning (gitleaks), SAST, dependency audit,
+container scanning, DAST. Reportar la matriz presente/ausente. Para
+materializar los faltantes: `/swl:configurar-ci --seguridad` (instala los
+workflows opt-in).
+
+## Capa 5 — Superficie LLM (condicional)
+
+Detectar stack LLM (deps `anthropic`, `openai`, `langchain`, `llama-index`,
+servidores MCP propios, prompts en el repo). Si existe — o con `--llm`:
+
+```
+Skill("ai-runtime-security")
+```
+
+Auditar: manejo de input no confiable hacia prompts (injection directa e
+indirecta), guardrails de salida, secretos en system prompts, gates de
+autonomía previos a tool-calls.
+
+## Capa 6 — Threat model (solo con `--threat-model`)
+
+```
+Skill("threat-model-lite")
+```
+
+Generar o actualizar `THREAT-MODEL.md` (STRIDE ligero: superficie de ataque,
+activos críticos, matriz de riesgo). Si ya existe uno, actualizarlo contra los
+endpoints/módulos nuevos en vez de regenerarlo desde cero.
+
+## Paso final — Reporte de postura consolidado
+
+Escribir `.planning/audit/seguridad-postura-[YYYY-MM-DD].md` (si no hay
+`.planning/`, ofrecer la raíz del proyecto):
+
+```markdown
+# Postura de seguridad — [proyecto] — [fecha]
+
+## Score por capa
+| Capa | Score | Veredicto |
+|------|-------|-----------|
+| 1. Secretos | N/100 | ... |
+| 2. Dependencias | N/100 | ... |
+| 3. Código OWASP | N/100 | ... |
+| 4. Pipeline CI | N/100 | ... |
+| 5. Superficie LLM | N/100 o N/A | ... |
+
+## VETO ITEMS DETECTADOS
+[secreto en historial, SQL injection, eval con input, CVE crítico sin parche…
+→ score global CAP a 60/100 con 1 veto, 30/100 con 2+. Formato de
+reglas/gobernanza.md § Veto items]
+
+## Hallazgos priorizados
+| # | Severidad (CVSSv3) | Capa | archivo:línea | Hallazgo | Remediación |
+
+## Acciones recomendadas (en orden)
+1. [acción — comando SWL que la ejecuta si existe]
+```
+
+Reportar al usuario el resumen con el score global y las top 3 acciones. Si
+hay hallazgos CRÍTICOS, recordar el flujo de remediación: `/swl:fix` (triage y
+reparación) o `/swl:verificar --solo-seguridad --until-converge` tras corregir.
+
+## Reglas de comportamiento
+
+- **Este comando NO modifica código ni secretos** — diagnostica y prioriza.
+  La remediación pasa por el flujo fix/verificar con el usuario al tanto.
+- Toda cita archivo:línea del reporte sale de `Read`/`Grep` reales de esta
+  corrida (`verificar-citas-normativas.md § Familia 2`).
+- Los veto items no se negocian ni se suavizan por presión de entrega
+  (`reglas/gobernanza.md`).
+- Con `--rapido`, decir explícitamente qué capas NO corrieron — un reporte
+  parcial presentado como completo es degradación silenciosa.
+- Falsos positivos de secretos (fixtures, ejemplos): verificarlos leyendo el
+  archivo antes de reportar; si son fixtures legítimos, recomendar renombrarlos
+  al patrón reconocible (`placeholder`, `example`, `dummy_`).

package/comandos/swl/status.md

@@ -1,6 +1,6 @@
 ---
 name: swl:status
-description: Comando unificado de observabilidad del sistema y la sesión. Enruta a subcomandos [salud | metricas | loops | evolucion | historico | dashboard] que reportan salud del sistema SWL, métricas de la sesión actual, trayectorias de loops iterativos, estado del ciclo de auto-evolución y dashboard histórico multi-sesión. Reemplaza los comandos previos /swl:salud, /swl:metricas, /swl:dashboard y /swl:evolucion-estado (fusionados en este desde la Fase 09).
+description: Comando unificado de observabilidad del sistema y la sesión. Enruta a subcomandos [salud | metricas | loops | evolucion | historico | dashboard | valor] que reportan salud del sistema SWL, métricas de la sesión actual, trayectorias de loops iterativos, estado del ciclo de auto-evolución y dashboard histórico multi-sesión. Reemplaza los comandos previos /swl:salud, /swl:metricas, /swl:dashboard y /swl:evolucion-estado (fusionados en este desde la Fase 09).
 allowed_tools: ["Read", "Write", "Bash", "Glob", "Grep"]
 ---
 
@@ -17,7 +17,8 @@ funcionalidad ni de flags.
 /swl:status salud                  — Diagnóstico de salud del sistema SWL (genera SALUD.md)
 /swl:status metricas               — Métricas de la sesión actual (tokens, costo, herramientas)
 /swl:status metricas detalle       — Desglose completo por herramienta, agente y timeline
-/swl:status metricas fases         — Progreso de fases del proyecto (desde feature-list.json)
+/swl:status metricas fases         — Progreso de fases del proyecto (desde feature-list.json)
+/swl:status valor                  — Evidencia de valor del harness en ESTE proyecto (intercepciones, defectos/escapes, DORA/CI, uso — con procedencia por métrica)
 /swl:status loops                  — Trayectorias de loops iterativos (.planning/loops/)
 /swl:status evolucion              — Estado del ciclo de auto-evolución (health_score, nudges…)
 /swl:status evolucion --json       — JSON crudo de metricas.json (para pipes)
@@ -44,7 +45,8 @@ como vista por defecto si el contexto lo sugiere.
 | `metricas` (+ `detalle`, `fases`) | scripts de métricas de sesión + `derivar-feature-list.js` | `/swl:metricas` |
 | `loops` | `hooks/lib/loop-telemetry.js` | `/swl:metricas loops` |
 | `evolucion` | `hooks/ciclo-evolucion.js` (etapa métricas) + `.planning/evolution/metricas.json` | `/swl:evolucion-estado` |
-| `dora` | `scripts/lib/metricas-dora.js` + `.planning/evolution/metricas-dora.json` | nuevo (Fase 15, ADR-0039) |
+| `dora` | `scripts/lib/metricas-dora.js` + `.planning/evolution/metricas-dora.json` | nuevo (Fase 15, ADR-0039) |
+| `valor` | CLI cross-scope `swl-ses valor` (`scripts/evidencia-valor.js`) — datos 100% locales; frontera y reglas anti-gaming en `docs/evidencia-valor.md` | nuevo (v2.5.1) |
 | `historico` / `dashboard` | `Skill("swl-dashboard")` | `/swl:dashboard` |
 
 ---

package/habilidades/aprendizaje-continuo/SKILL.md

@@ -6,7 +6,7 @@ description: >
   tres scopes (proyecto/dominio/global), degradacion automatica por contradiccion,
   promocion a skills/comandos/agentes, evolucion (merge, split, deprecate) y
   proteccion contra contaminacion cross-proyecto.
-version: "1.0.1"
+version: "1.0.2"
 herramientasPermitidas: [Read]
 exclusiones:
   - "No cargar para consultar instintos ya cargados en la sesión actual — si el perfil fue leído, re-cargarlo es desperdicio de contexto."
@@ -137,6 +137,8 @@ ver [recursos/referencia-instintos.md](recursos/referencia-instintos.md).
 
 ## Gotchas / Errores comunes no obvios
 
+- **El relleno real de un sistema de agentes no son componentes muertos sino conocimiento sin cablear** [auditoría 2026-07-08 sobre 182 skills]: la cross-referencia de cableado mostró 120/182 skills con >5 referencias (sistema sano) y solo 2 genuinamente fuera de dominio; las 7 "huérfanas" restantes eran conocimiento de ALTO valor (doubt-driven-review, devsecops-pipeline-security, ai-runtime-security…) que ningún flujo aprovechaba — bajaron a 1 tras cablearlas a comandos y `skillsInvocables`. Método correcto de auditoría de bloat: (1) cross-referencia estática (`scripts/audit-tools/auditar-relleno-inventario.js`), (2) telemetría de uso real (`.planning/skill-metrics.json` del hook `telemetria-skill-routing`), (3) filtro de dominio del proyecto. El instinto de "borrar lo que no se usa" está mal calibrado sin el paso 3: la acción correcta para huérfanas de valor es CABLEAR, no eliminar.
+
 - **Instinto de scope global demasiado específico de un framework**: un instinto como "En FastAPI siempre usar `selectinload`" se promueve a `global.yaml` porque tuvo alta confianza. Causa: el criterio de promoción no verificó que el patrón sea cross-proyecto y no de dominio. Solución: antes de mover a global, aplicar el filtro "¿le sirve esto a un ingeniero en cualquier stack?"; si no, mantenerlo en `dominio.yaml` o `proyecto.yaml`.
 - **Hooks de observación con exit code != 0 interrumpen la sesión**: el hook `observe-pre.js` lanza una excepción y Claude Code detiene la tarea en curso. Causa: violación de la regla "los hooks de observación NUNCA deben producir exit code != 0". Solución: envolver toda la lógica del hook en `try/catch` y loggear el error al stderr sin propagarlo — la observabilidad nunca debe bloquear el trabajo productivo.
 - **Duplicación de instintos entre `proyecto.yaml` y `APRENDIZAJES.md`**: el mismo anti-patrón existe en ambos canales con información inconsistente. Causa: el instinto se creó manualmente sin verificar si ya había una entrada en APRENDIZAJES.md. Solución: antes de crear un instinto nuevo, ejecutar `memoria-busqueda` para verificar si ya existe en otro canal; si existe, actualizar el canal correcto según `reglas/memoria-consolidada.md`.

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. Inicia con discovery routing (5 paths) que evita el cuestionario completo cuando no aplica.
-version: "1.1.0"
+description: Cuestionario adaptativo canónico que se ejecuta antes de planear una fase de desarrollo (única fuente de la entrevista — el comando /swl:discutir-fase la consume de aquí). Extrae decisiones técnicas y de negocio con bloque universal + bloques por dominio (backend, frontend, infra, integración, datos/migración), clasifica respuestas como "cerradas" (no negociables) o "abiertas" (decisión delegada al agente), y produce un CONTEXTO.md que alimenta al planificador. Inicia con discovery routing (5 paths) que evita el cuestionario completo cuando no aplica.
+version: "1.3.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`."
@@ -57,8 +57,8 @@ Si no hay `.planning/`, marca **proyecto verde** y salta al cuestionario complet
 |------|--------------|--------|
 | **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_C** — Nueva fase single-scope | Petición nueva, no encaja en fases existentes, single-domain. | Ejecutar cuestionario completo (Bloques 1-5, con el bloque de dominio que aplique). |
+| **RUTA_D** — Nueva fase multi-domain (ADR-0020) | Petición nueva que cruza múltiples dominios y requiere sub-tareas paralelas. | Cuestionario completo (Bloques 1-5, combinando los bloques de dominio aplicables) + planificación de paralelización. Si además produciría >20 tareas en una sola fase, sugerir descomposición en N fases y confirmar con el usuario. |
 | **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
@@ -107,41 +107,85 @@ notifica explícitamente antes de proceder.
 
 ## Bloque 1 — Contexto de la fase (siempre preguntar)
 
-1. ¿Cuál es el objetivo principal de esta fase en una oración?
-2. ¿Qué debe existir y funcionar al finalizar esta fase para considerarla exitosa?
-3. ¿Hay alguna restricción de tiempo (deadline, demo, sprint)?
-4. ¿Alguna decisión tomada en fases anteriores afecta el alcance de esta?
+1. ¿Cuál es el objetivo principal de esta fase en una oración? ¿Cuál es el entregable más importante?
+2. ¿Qué debe existir y funcionar al finalizar para considerarla exitosa? ¿Cómo sabremos que está terminada?
+3. ¿Hay algo de esta fase que NO quedó claro en el roadmap y debemos aclarar ahora?
+4. ¿Hay restricciones de tiempo (deadline, demo, sprint) o de presupuesto (costo de infra, servicios de terceros, licencias)?
+5. ¿Alguna decisión de fases anteriores (o de producto) afecta el alcance de esta?
+6. ¿Qué estamos asumiendo como cierto sin haberlo verificado? (supuestos explícitos — "ningún supuesto" es respuesta sospechosa: indagar al menos uno)
 
 ---
 
-## Bloque 2 — Decisiones técnicas (preguntar si aplica)
+## Bloque 2 — Dominio (adaptativo: elegir según el tipo de fase)
+
+Determina el tipo leyendo la descripción de la fase. Las fases mixtas combinan
+los bloques aplicables. **Si hay código nuevo, al menos un bloque de dominio
+siempre aplica** — omitirlo por considerarlo "técnico" es el error más común.
+
+**Backend/API:**
+- ¿Qué entidades de datos nuevas introduce? Campos principales.
+- ¿Qué endpoints o servicios expone? ¿Se modifica alguno existente? ¿Rompe compatibilidad con consumidores actuales?
+- ¿Hay reglas de negocio complejas o cálculos? ¿Qué validaciones son críticas — qué datos nunca deben llegar corruptos a la BD?
+- ¿Quién tiene permiso de acceder a qué? ¿Cambia autenticación, roles o restricciones?
+- ¿Se manejan datos personales o sensibles (PII)? ¿Hay requisitos de retención o regulatorios?
+
+**Frontend/UI:**
+- ¿Qué pantallas o vistas nuevas introduce? Descríbelas.
+- ¿Cuál es el flujo principal del usuario? (de dónde viene, qué hace, adónde va) ¿Qué usuarios/segmentos se ven afectados?
+- ¿Hay componentes reutilizables del sistema de diseño existente?
+- ¿Qué datos consume cada pantalla y de qué endpoints?
+- ¿Estados de carga, error y vacío considerados explícitamente?
+
+**Infraestructura:**
+- ¿Entorno objetivo? (dev/staging/prod y sus diferencias)
+- ¿Secretos o variables de entorno nuevas?
+- ¿Qué servicios gestionados (cloud) se usan? ¿Costo estimado?
+- ¿Estrategia de rollback si el despliegue sale mal?
+- ¿Se documenta el proceso de despliegue para el equipo (runbook)?
+
+**Integración:**
+- ¿Qué sistema externo se integra? ¿Hay documentación de su API y sandbox de pruebas?
+- ¿Qué pasa si el sistema externo no responde? ¿Timeout y retry definidos?
+- ¿Sincronización en tiempo real o batch? ¿Transformaciones de datos entre formatos?
+- ¿Qué versión del contrato externo se asume y qué pasa si cambia?
+
+**Datos/Migración:**
+- ¿Qué volumen de datos se migra o transforma? ¿Hay ventana de mantenimiento o debe ser sin downtime (expand-contract)?
+- ¿Cuál es el plan de rollback si la migración falla a la mitad? ¿Los cambios de schema son reversibles?
+- ¿Cómo se verifica la integridad post-migración (conteos, checksums, muestreo)?
+- ¿Hay consumidores del schema viejo que deben seguir funcionando durante la transición?
+- ¿Se necesita respaldo previo verificado? ¿Quién lo autoriza?
 
-Preguntar solo si la fase involucra código nuevo o cambios de arquitectura:
+---
 
-5. ¿Se crean nuevas entidades de base de datos? ¿Cuáles?
-6. ¿Se expone una nueva API pública o se modifican endpoints existentes?
-7. ¿Hay integraciones con sistemas externos en esta fase?
-8. ¿Se espera algún cambio en la autenticación o los permisos?
-9. ¿Hay requerimientos de rendimiento específicos para esta fase?
+## Bloque 3 — Calidad, proceso y operación (preguntar si aplica)
 
----
+- ¿Se requieren tests unitarios, de integración o ambos? (TDD es default ON — gate G2; solo registrar opt-out con razón)
+- ¿Hay features que requieren revisión de seguridad antes de merge?
+- ¿Requerimientos no funcionales: latencia objetivo, carga esperada, concurrencia, disponibilidad?
+- ¿Qué observabilidad debe emitir la fase (logs estructurados, métricas, alertas)? ¿Cómo sabremos en producción que funciona — o que dejó de funcionar?
+- ¿Deployment independiente o junto con otras fases? ¿Reversible?
+- ¿Features "nice to have" que pueden salir del scope si falta tiempo?
 
-## Bloque 3 — Calidad y proceso (preguntar si aplica)
+---
 
-Preguntar si el equipo tiene proceso definido o si la fase es crítica:
+## Bloque 4 — Dependencias y riesgos (siempre preguntar)
 
-10. ¿Se requieren tests unitarios, de integración o ambos en esta fase?
-11. ¿Hay features que requieren revisión de seguridad antes de merge?
-12. ¿Se va a hacer deployment de esta fase de forma independiente o junto con otras?
-13. ¿Hay features marcadas como "nice to have" que pueden salir del scope si hay tiempo?
+- ¿Hay tareas que dependen de trabajo de otro equipo o sistema externo?
+- ¿Cuáles son los riesgos más grandes de esta fase? ¿Alguno podría bloquear una tarea?
+- ¿Hay deuda técnica que DEBE resolverse antes o durante esta fase?
 
 ---
 
-## Bloque 4 — Dependencias y riesgos (siempre preguntar)
+## Bloque 5 — Criterios de aceptación (siempre, al final)
 
-14. ¿Hay tareas en esta fase que dependen de trabajo de otro equipo o sistema externo?
-15. ¿Hay algún riesgo técnico conocido que podría bloquear alguna tarea?
-16. ¿Hay deuda técnica existente que DEBE resolverse antes o durante esta fase?
+- ¿Qué debe demostrarse al usuario/cliente para que la fase se apruebe?
+- ¿Hay pruebas específicas que deben pasar? (humo, carga, usuario)
+- ¿Quién da el visto bueno final?
+- ¿Cómo se medirá el éxito en producción — qué outcome observable mejora para el usuario, y qué NO debe degradarse? (métrica de outcome ≠ criterio de aceptación; ver `Skill("proceso-intent-engineering")` § Desired Outcomes cuando la fase lo amerite)
+
+Los criterios se registran como REQ-IDs binarios verificables (`REQ-<fase>-NN`,
+trazabilidad G4) — formato exacto en `recursos/plantilla-contexto.md`.
 
 ---
 
@@ -163,66 +207,22 @@ Señalar la contradicción explícitamente: "Mencionaste X antes pero ahora Y.
 
 ## Plantilla de salida: `.planning/fases/0N-CONTEXTO.md`
 
-```markdown
-# CONTEXTO.md — Fase [N]: [Nombre]
-**Fecha de discusión**: [fecha]
-**Participantes**: [usuario, agente]
-
-## Objetivo de la fase
-[Respuesta del usuario a pregunta 1 y 2]
-
-## Criterio de éxito
-[Lo que debe existir y funcionar al terminar]
-
-## Restricciones de tiempo
-- Deadline: [fecha o "sin deadline definido"]
-- Sprint: [número si aplica]
-
-## Decisiones técnicas
-
-| ID  | Decisión | Tipo | Notas |
-|-----|---------|------|-------|
-| D-01 | [decisión] | CERRADA | [contexto] |
-| D-02 | [decisión] | ABIERTA | [el agente decidirá X porque Y] |
-| D-03 | [decisión] | PENDIENTE | [bloquea tarea T] |
-
-## Alcance confirmado
-### Incluido en esta fase
-- Feature A
-- Feature B
-
-### Explícitamente excluido
-- Feature C (pasa a siguiente fase)
-
-## Dependencias externas
-| Dependencia | Equipo/Sistema | Estado | Riesgo |
-|------------|---------------|--------|--------|
-|            |               |        |        |
-
-## Riesgos identificados
-| Riesgo | Probabilidad | Impacto | Mitigación |
-|--------|-------------|---------|-----------|
-|        |             |         |           |
-
-## Deuda técnica a resolver
-- [ ] [deuda 1] — obligatoria
-- [ ] [deuda 2] — si hay tiempo
-
-## Decisiones pendientes (bloqueos)
-- [ ] [decisión] — necesaria antes de [tarea]
-
-## Notas de la discusión
-[Contexto adicional, cambios de opinión, razonamiento detrás de decisiones]
-```
+La estructura canónica del archivo (frontmatter con gate TDD, tabla de
+decisiones CERRADA/ABIERTA/PENDIENTE, supuestos, no-goals, criterios de
+aceptación con REQ-IDs G4, métrica de outcome, NFRs, rollback, riesgos y
+dependencias) vive en **`recursos/plantilla-contexto.md`** — única fuente,
+compartida con el comando `/swl:discutir-fase`. Leerla antes de escribir el
+archivo; no reconstruirla de memoria.
 
 ---
 
 ## Gotchas / Errores comunes no obvios
 
 - **Respuesta "como siempre" archivada sin verificar**: el usuario dice "igual que en la fase anterior" y el agente asume que el patrón aplica sin leer el CONTEXTO.md previo. Causa: confianza en el modelo mental sin verificación. Solución: siempre leer el CONTEXTO.md de la fase anterior antes de aceptar la respuesta.
-- **Decisiones PENDIENTE que bloquean el plan ignoradas**: el agente avanza a `planear-fase` con ítems de los Bloques 1 o 4 en estado PENDIENTE. Causa: no se aplicó la Regla 3. Solución: verificar explícitamente que ningún ítem crítico quede PENDIENTE antes de cerrar la discusión.
+- **Decisiones PENDIENTE que bloquean el plan ignoradas**: el agente avanza a `planear-fase` con ítems de los Bloques 1, 4 o 5 en estado PENDIENTE. Causa: no se aplicó la Regla 3. Solución: verificar explícitamente que ningún ítem crítico quede PENDIENTE antes de cerrar la discusión.
 - **CONTEXTO.md escrito sin confirmar criterio de éxito verificable**: el usuario da un objetivo vago ("mejorar rendimiento") y se registra sin cuestionarlo. Causa: el agente no aplica la prueba de observabilidad. Solución: pedir reformulación hasta que el criterio sea binario y observable.
-- **Bloque 2 omitido cuando sí aplica**: si la fase incluye nuevas entidades de BD o endpoints pero el agente saltó el Bloque 2 por considerarlo "técnico". Causa: interpretación laxa de "preguntar si aplica". Solución: si hay código nuevo, el Bloque 2 siempre aplica.
+- **Bloque de dominio omitido cuando sí aplica**: la fase incluye nuevas entidades de BD o endpoints pero el agente saltó el Bloque 2 por considerarlo "técnico". Causa: interpretación laxa de "preguntar si aplica". Solución: si hay código nuevo, al menos un bloque de dominio siempre aplica.
+- **Fase con migración de datos sin preguntas de rollback**: la fase toca schema o migra datos pero el agente usó solo el bloque backend y nunca preguntó por reversibilidad ni verificación de integridad. Causa: no combinar bloques en fases mixtas. Solución: cualquier cambio destructivo de datos activa el bloque Datos/Migración completo.
 
 ## Checklist de cierre de discusión
 
@@ -230,7 +230,10 @@ Antes de pasar a `planear-fase`, verificar:
 
 - [ ] El objetivo de la fase es una oración accionable (no "mejorar el sistema")
 - [ ] El criterio de éxito es verificable (observable sin ambigüedad)
-- [ ] No hay decisiones PENDIENTE en ítems de los Bloques 1 y 4
+- [ ] No hay decisiones PENDIENTE en ítems de los Bloques 1, 4 y 5
 - [ ] Todas las decisiones ABIERTA tienen una nota de qué decidirá el agente
 - [ ] Las features excluidas están documentadas explícitamente
-- [ ] CONTEXTO.md guardado en `.planning/fases/`
+- [ ] Los supuestos explícitos quedaron registrados (al menos uno, o justificación de por qué no hay)
+- [ ] Si la fase toca datos/schema: rollback y verificación de integridad respondidos
+- [ ] Los criterios de aceptación tienen REQ-IDs binarios verificables
+- [ ] CONTEXTO.md guardado en `.planning/fases/` siguiendo `recursos/plantilla-contexto.md`