@saulwade/swl-ses 2.4.3 → 2.5.2

package/habilidades/discutir-fase/recursos/plantilla-contexto.md

@@ -0,0 +1,136 @@
+# Plantilla canónica de `.planning/fases/0N-CONTEXTO.md`
+
+Única fuente de la estructura del CONTEXTO.md. La consumen `Skill("discutir-fase")`
+y el comando `/swl:discutir-fase`. Las secciones marcadas *(si aplica)* se omiten
+cuando la fase no las toca — un CONTEXTO.md corto y denso es mejor que uno con
+secciones vacías.
+
+```markdown
+# Contexto de la Fase N — [nombre de la fase]
+
+**Proyecto**: [nombre del proyecto]
+**Fase**: N de M (total de fases en el roadmap)
+**Fecha de discusión**: [fecha actual]
+**Estado**: Listo para planear
+**TDD**: on  <!-- default (gate G2). Si el usuario lo desactiva: `off — razón: [...]` + entry en AUDITORIA.md -->
+
+## Objetivo de la fase
+[una oración accionable — no "mejorar el sistema"]
+
+## Criterio de éxito
+[qué debe existir y funcionar al terminar; binario y observable]
+
+## Restricciones
+- Tiempo: [deadline / demo / sprint, o "sin deadline definido"]
+- Presupuesto: [costo de infra/servicios/licencias si aplica, o "sin restricción declarada"]
+- Capacidad: [disponibilidad del equipo / ventana de despliegue si aplica]
+
+## Supuestos explícitos
+[lista de lo que se asume cierto sin haberlo verificado; cada supuesto con su
+consecuencia si resulta falso. "Sin supuestos" es respuesta sospechosa — indagar.]
+
+## Entregables esperados
+- [ ] [entregable 1]
+- [ ] [entregable 2]
+
+## Requisitos técnicos
+[lista detallada]
+
+## Reglas de negocio
+[lista numerada]
+
+## Modelos de datos *(si aplica)*
+[entidades y campos clave]
+
+## Endpoints / servicios *(si aplica)*
+[método, ruta y propósito]
+
+## Pantallas / vistas *(si aplica)*
+[descripción de pantallas y flujo de usuario]
+
+## Decisiones técnicas
+
+| ID   | Decisión | Tipo | Notas |
+|------|----------|------|-------|
+| D-01 | [decisión] | CERRADA | [no negociable — contexto] |
+| D-02 | [decisión] | ABIERTA | [el agente decidirá X porque Y] |
+| D-03 | [decisión] | PENDIENTE | [bloquea tarea T — resolver antes de planear] |
+
+## Alcance confirmado
+### Incluido en esta fase
+- Feature A
+### Explícitamente excluido (no-goals)
+- Feature C (pasa a fase siguiente — razón)
+
+## Criterios de aceptación (REQ)
+[criterios binarios y verificables con ID estable namespaceado por fase
+`REQ-<fase>-NN` (DT-IDS-NAMESPACE, fases ≥12) — trazabilidad G4:
+- **REQ-12-01**: [criterio binario verificable]
+- **REQ-12-02**: [criterio binario verificable]
+Las fases 01-11 conservan el formato plano `REQ-NN` (gracia legacy permanente,
+no se renumeran). `verificar-trazabilidad.js` acepta ambos formatos.
+Un REQ emitido NUNCA se renumera ni se reusa: si un criterio se descarta, marcarlo
+"RETIRADO — razón" conservando el número. planear-fase exige que cada tarea T-NN
+declare qué REQ verifica (matriz REQ×T) y aprobar-plan rechaza planes con REQ
+huérfanos. verificar-trazabilidad.js valida la cadena REQ→T→commit→test al cierre.
+Método de verificación: por default cada REQ exige un test con marker
+`verifica: REQ-<fase>-NN`; los REQ satisfechos por prosa/docs/configuración llevan
+la anotación `(verificación: inspección)` en el criterio — exigen tarea y commit
+pero no test automatizado.]
+
+## Métrica de outcome *(si aplica)*
+[cómo se medirá el éxito en producción, desde la perspectiva del usuario —
+observable sin self-report. Distinto del criterio de aceptación (que es
+funcional/binario). Ej: "el tiempo de captura de un expediente baja de 12 a 5
+minutos". Incluir qué NO debe degradarse (health metric).]
+
+## Requisitos no funcionales *(si aplica)*
+- Rendimiento: [latencia objetivo, carga esperada, concurrencia]
+- Disponibilidad / escalabilidad: [...]
+- Observabilidad: [logs/métricas/alertas que la fase debe emitir]
+
+## Datos sensibles y privacidad *(si aplica)*
+[PII manejada, retención, requisitos regulatorios]
+
+## Compatibilidad *(si aplica)*
+[breaking changes, contratos con consumidores existentes, versiones de API,
+soporte de navegadores/clientes]
+
+## Reversibilidad / rollback *(si aplica)*
+[cómo se revierte la fase si sale mal — obligatorio si hay migraciones de datos,
+cambios de schema destructivos o despliegues de infraestructura]
+
+## Riesgos identificados
+
+| Riesgo | Probabilidad | Impacto | Mitigación |
+|--------|--------------|---------|------------|
+|        | ALTA/MEDIA/BAJA | ALTO/MEDIO/BAJO |     |
+
+## Dependencias
+
+| Dependencia | Equipo/Sistema | Estado | Riesgo |
+|-------------|----------------|--------|--------|
+|             |                |        |        |
+
+[incluye: fases previas requeridas, sistemas externos, trabajo de otros equipos]
+
+## Deuda técnica a resolver
+- [ ] [deuda 1] — obligatoria antes/durante la fase
+- [ ] [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]
+```
+
+## Reglas de llenado
+
+- El archivo debe ser comprensible sin haber participado en la conversación.
+- Español de México, Markdown limpio.
+- Toda decisión registrada lleva tipo `CERRADA` / `ABIERTA` / `PENDIENTE`
+  (taxonomía canónica — el marcador legacy `[POR DEFINIR]` se mapea a
+  `ABIERTA` si el usuario delega, o `PENDIENTE` si bloquea el plan).
+- No cerrar la discusión con `PENDIENTE` en ítems críticos (objetivo, alcance,
+  modelo de datos, permisos, rollback de migraciones) — regla 3 del skill.

package/habilidades/doc-sync/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: doc-sync
 description: Sincronización de documentación con el estado actual del código. Detecta documentos desactualizados (README, ADRs, docstrings, comentarios de API), genera un changelog estructurado de los cambios relevantes, y mantiene los Architecture Decision Records (ADRs) actualizados con las decisiones tomadas durante el desarrollo.
-version: "1.3.0"
+version: "1.4.0"
 herramientasPermitidas: [Read, Bash, Glob, Grep]
 exclusiones:
   - "No cargar para crear documentación nueva desde cero — este skill sincroniza documentación existente con el código actual; para crear documentación de feature nueva usar `documentador-swl` o escribir el README/ADR directamente."
@@ -709,6 +709,8 @@ el código implementado. La doc desactualizada es deuda técnica de primer nivel
 
 ## Gotchas / Errores comunes no obvios
 
+- **Catálogo mantenido a mano = drift garantizado; la corrección estructural es generar desde la fuente + gate `--check` en CI** [CONFIRMADO x4 en una sola auditoría, 2026-07-08]: (1) AGENTS.md con nombres de skill corruptos por find/replace de marca (`workflow-Codex` — la invocación Skill() fallaba) y 6 comandos ausentes de la tabla, incluido `aprobar-plan` (el gate G1); (2) COMANDOS.md con flags stale en 3 comandos y una fila duplicada divergente; (3) MAPEO_SKILLS_AGENTES con mapeos falsos en 3/5 agentes muestreados y skills retiradas, pese a ser insumo del gate de release; (4) README con 3 cifras contradictorias dentro del mismo archivo. Jerarquía de defensas: *verificación* (gates de contadores) atrapa números; solo la *generación* (marcadores BEGIN/END + script desde frontmatter/manifiestos, como `generar-comandos.js` y `generar-inventario.js`) atrapa contenido. Al crear cualquier tabla nueva de componentes en docs, preguntar primero: ¿esto puede generarse? Si sí, generarlo desde el día uno. Corolario [caso briefing.js]: los nombres de comandos citados en STRINGS de hooks/libs también driftan (recomendaba `/swl:evolucion-estado`, retirado meses atrás) — al retirar o fusionar un comando, `grep -rn "swl:<viejo>" hooks/ scripts/ gateway/` es parte del checklist de retiro.
+
 - **README marcado como desactualizado porque `grep` encontró un nombre de variable cambiado en un comentario**: el Paso 2 busca variables de entorno que aparezcan en el código pero no en `.env.example`, y el agente concluye que el README está obsoleto. Causa: el grep de variables detecta comentarios y strings de ejemplo, no solo declaraciones reales. Solución: al comparar variables de entorno, filtrar por el patrón de uso real (`os.getenv`, `process.env`, `os.environ`) y excluir archivos de ejemplo y tests.
 - **ADR marcado como "Obsoleto" en lugar de "Reemplazado por ADR-NNN"**: el agente marca decisiones revertidas como obsoletas sin crear el ADR de reemplazo primero. Causa: el estado "Obsoleto" se usa cuando no hay decisión sustituta; "Reemplazado" requiere que el ADR sustituto ya exista. Solución: si la decisión fue reemplazada por otra (no solo abandonada), crear el ADR de reemplazo en el mismo commit y referenciar el número — nunca marcar como "Reemplazado por ADR-NNN" si ese ADR no existe aún.
 - **Changelog generado desde `git log` incluye commits de fix de typo y WIP que no son relevantes para usuarios**: el changelog resultante tiene 40 entradas de "fix: typo" y "wip: progress". Causa: `git log --pretty=format:"- %s"` incluye todos los commits sin filtrar. Solución: usar `git log` con filtros por tipo de commit convencional (`feat:`, `fix:`, `security:`, `BREAKING CHANGE:`) y excluir commits de WIP, typo y refactor — el changelog es para consumidores del paquete, no para el historial interno.

package/habilidades/doubt-driven-review/SKILL.md

@@ -9,7 +9,7 @@ description: >
   memoria (eso lo hace red-team-swl) ni de seguridad de código (eso lo hace
   revisor-seguridad-swl) — este skill se especializa en decisiones técnicas
   con costo de cambio alto.
-version: "1.0.0"
+version: "1.1.0"
 exclusiones:
   - "No cargar para revisión de memoria SWL (APRENDIZAJES.md, instintos/) — esa es responsabilidad de red-team-swl."
   - "No cargar para auditoría de seguridad de código (OWASP, CVEs, inyección) — usar revisor-seguridad-swl."
@@ -156,8 +156,22 @@ no en hipótesis falsable. Documentarla como tal en el reporte.
 - **Convertirlo en proceso burocrático**: aplicar doubt-driven a decisiones
   reversibles es overhead. El paso 1 filtra esto explícitamente.
 
+## Entrada operacional
+
+Este skill tiene dos vías de invocación en el sistema:
+
+1. **`abogado-diablo-swl`** (vía principal) — el agente lo carga en su Fase 0 y
+   ejecuta los 5 pasos añadiendo pre-mortem y dictamen. Punto de entrada del
+   usuario: `/swl:predecir --abogado-diablo`.
+2. **Carga directa** por un agente distinto al decisor (ej: `arquitecto-swl`
+   decidió → otro agente ejecuta el skill sobre la decisión) — válida cuando no
+   se necesita el pre-mortem completo.
+
 ## Relación con otras capacidades del sistema
 
+- `abogado-diablo-swl`: el agente que operacionaliza este skill (pre-mortem +
+  dictamen PROCEDER/CON CONDICIONES/NO PROCEDER). Este skill define el protocolo;
+  el agente lo ejecuta con separación decisor/crítico garantizada.
 - `red-team-swl`: cubre adversarial review de **memoria del sistema** (perfil-usuario,
   instintos, APRENDIZAJES). Doubt-driven cubre **decisiones técnicas**. NO duplicación.
 - `arquitecto-swl`: produce ADRs. Doubt-driven se carga ANTES de aceptar el ADR.