@saulwade/swl-ses 1.4.1 → 1.5.0

package/comandos/swl/contribuir.md

@@ -1,233 +1,233 @@
----
-name: swl:contribuir
-description: Contribuye evoluciones de _userland/ al core de swl-ses creando un PR en GitHub. Filtra por dominio (solo ingeniería de software general), evalúa calidad con PluginEval (score ≥80 requerido) y crea el PR vía gh CLI. Flags: --skill=[nombre], --agente=[nombre], --dry-run.
-allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Agent"]
----
-
-# /swl:contribuir — Contribuir evoluciones al core de swl-ses
-
-Eres el facilitador de contribuciones del sistema SWL. Tu responsabilidad es tomar evoluciones que un usuario creó en `_userland/` y, si pasan los filtros de calidad y dominio, crear un Pull Request contra el repositorio oficial de swl-ses.
-
-**Principio**: las evoluciones específicas de un proyecto se quedan en `_userland/` — solo evoluciones de dominio general pasan al core. Un skill de "configuración de Stripe para mi SaaS" no sube; un skill de "patrones de testing de APIs de pago" sí.
-
-## Cuándo usar este comando
-
-- Cuando el usuario evolucionó un agente o skill en `_userland/` y quiere compartirlo con la comunidad
-- Después de `/swl:evolucionar` cuando el cambio aplica a cualquier proyecto de software
-- Cuando se creó un skill nuevo con `/swl:crear-skill` que resuelve un problema general de ingeniería
-
-## Prerrequisitos
-
-1. **GitHub CLI (`gh`) autenticado** — verificar con `gh auth status`
-2. **Evolución marcada** — el artefacto debe tener `evolved: true` en frontmatter o existir en `_userland/`
-3. **Repositorio swl-ses accesible** — se necesita permiso de fork/PR
-
-## Flags soportados
-
-```
---skill=[nombre]      Contribuir solo el skill indicado de _userland/habilidades/
---agente=[nombre]     Contribuir solo el agente indicado de _userland/agentes/
---dry-run             Ejecutar validaciones y evaluación sin crear PR
-```
-
-Si no se pasa flag, escanea todo `_userland/` buscando candidatos.
-
-## Paso 0 — Verificar prerrequisitos
-
-Verificar que `gh` está instalado y autenticado:
-
-```bash
-gh auth status
-```
-
-Si falla:
-- **No instalado**: indicar al usuario que instale GitHub CLI (ver MANUAL_USO.md § Dependencias externas)
-- **No autenticado**: indicar al usuario que ejecute `! gh auth login` desde el prompt de Claude Code
-
-DETENER si `gh auth status` no reporta una cuenta autenticada.
-
-## Paso 1 — Escanear candidatos en _userland/
-
-Buscar artefactos en `_userland/habilidades/` y `_userland/agentes/`:
-
-```bash
-# Skills con SKILL.md
-for dir in _userland/habilidades/*/; do
-  [ -f "$dir/SKILL.md" ] && echo "skill: $(basename $dir)"
-done
-
-# Agentes con .md
-for f in _userland/agentes/*.md; do
-  [ -f "$f" ] && echo "agente: $(basename $f .md)"
-done
-```
-
-Si se pasó `--skill` o `--agente`, filtrar a solo ese candidato.
-
-Si no hay candidatos, informar:
-```
-No se encontraron evoluciones en _userland/ para contribuir.
-Usa /swl:evolucionar o /swl:crear-skill para generar evoluciones primero.
-```
-
-## Paso 2 — Filtro de dominio
-
-Para cada candidato, leer su contenido y evaluar compatibilidad de dominio.
-
-**Pregunta de filtro**: *¿Le sirve esto a un ingeniero de software en cualquier proyecto de software?*
-
-**Dominios aceptados** (ingeniería de software general):
-- SDLC, backend, frontend, QA, DevOps, seguridad, arquitectura
-- Testing, CI/CD, monitoreo, observabilidad
-- Patrones de diseño, refactoring, revisión de código
-- APIs, bases de datos, infraestructura cloud
-
-**Dominios rechazados** (verticales específicos):
-- ML/AI productivo, ciencia de datos, bioinformática
-- Finanzas, contabilidad, legal
-- Dominio de negocio específico del proyecto
-
-Para cada candidato rechazado, explicar por qué:
-```
-RECHAZADO: [nombre] — dominio "[dominio detectado]" no es ingeniería de software general.
-Las evoluciones específicas de dominio se mantienen en _userland/ del proyecto.
-```
-
-## Paso 3 — Evaluación PluginEval
-
-Para cada candidato que pasó el filtro de dominio, ejecutar evaluación de calidad.
-
-Cargar:
-```
-Skill("evaluacion-agentes")
-```
-
-Ejecutar evaluación completa (2 capas). El score mínimo para contribuir es **80/100** (badge Oro).
-
-- **Score ≥ 80**: APROBADO — continuar al siguiente paso
-- **Score 60-79**: RECHAZADO con recomendaciones de mejora
-- **Score < 60**: RECHAZADO — necesita trabajo significativo
-
-```
-EVALUACIÓN: [nombre]
-  Capa 1 (estática): [N] errores, [N] advertencias
-  Capa 2 (semántica): [score]/100 — badge [badge]
-  Veredicto: [APROBADO | RECHAZADO]
-  [Si rechazado: top 3 mejoras recomendadas]
-```
-
-Si `--dry-run`: presentar resultados de evaluación y TERMINAR.
-
-## Paso 4 — Preparar contribución
-
-Para cada candidato aprobado:
-
-1. **Guardar ruta del workspace original** antes de cambiar de directorio:
-   ```bash
-   WORKSPACE_DIR=$(pwd)
-   ```
-
-2. **Crear fork** (si no existe) del repo oficial de swl-ses y obtener el nombre del fork:
-   ```bash
-   gh repo fork saul-wade/swl-ses --clone=false
-   FORK_REPO=$(gh api user --jq '.login')/swl-ses
-   ```
-
-3. **Clonar el fork** y crear branch descriptivo:
-   ```bash
-   gh repo clone "$FORK_REPO" /tmp/swl-ses-contrib
-   cd /tmp/swl-ses-contrib
-   git checkout -b contrib/[tipo]-[nombre]
-   ```
-
-4. **Copiar artefacto** desde el workspace original al clon del fork:
-   - Skills: `$WORKSPACE_DIR/_userland/habilidades/[nombre]/` → `habilidades/[nombre]/`
-   - Agentes: `$WORKSPACE_DIR/_userland/agentes/[nombre].md` → `agentes/[nombre].md`
-
-4. **Ajustar frontmatter** — agregar campos de contribución:
-   ```yaml
-   contributed: true
-   contributed-from: "_userland"
-   contributed-at: "[fecha YYYY-MM-DD]"
-   contributed-by: "[usuario gh]"
-   plugineval-score: [score]
-   ```
-
-5. **Registrar en plugin.json** si es necesario
-
-## Paso 5 — Crear Pull Request
-
-Crear el PR con template estructurado:
-
-```bash
-git add .
-git commit -m "contrib([tipo]): agrega [nombre] desde _userland
-
-Evaluado con PluginEval: [score]/100 (badge [badge]).
-Dominio: ingeniería de software general.
-
-Co-Authored-By: swl-ses <noreply@swl-ses>"
-
-git push origin contrib/[tipo]-[nombre]
-
-gh pr create \
-  --repo saul-wade/swl-ses \
-  --title "contrib([tipo]): [nombre]" \
-  --body "$(cat <<'EOF'
-## Contribución desde _userland
-
-**Tipo**: [skill | agente]
-**Nombre**: [nombre]
-**Dominio**: [dominio detectado]
-**PluginEval**: [score]/100 — badge [badge]
-
-## Descripción
-
-[Descripción extraída del artefacto]
-
-## Evidencia de calidad
-
-- Capa 1 (estática): [N] errores, [N] advertencias
-- Capa 2 (semántica): [score]/100
-- Filtro de dominio: APROBADO (ingeniería de software general)
-
-## Checklist
-
-- [ ] Score PluginEval ≥ 80
-- [ ] Dominio: ingeniería de software general
-- [ ] Sin credenciales hardcodeadas
-- [ ] Frontmatter válido
-- [ ] No duplica skill/agente existente
-
----
-Generado por `/swl:contribuir` — swl-ses v[versión]
-EOF
-)"
-```
-
-## Paso 6 — Reporte final
-
-```
-=== Contribución completada ===
-
-Candidatos escaneados: [N]
-Filtro de dominio:     [N] aprobados, [N] rechazados
-Evaluación PluginEval: [N] aprobados (≥80), [N] rechazados
-PRs creados:           [N]
-
-[Para cada PR creado:]
-  → [nombre]: [URL del PR]
-
-Los PRs serán revisados por los mantenedores de swl-ses.
-```
-
-## Reglas de comportamiento
-
-- NUNCA crear un PR sin que el candidato haya pasado AMBOS filtros (dominio + PluginEval ≥ 80).
-- NUNCA contribuir artefactos que contengan credenciales, tokens o datos del proyecto del usuario.
-- NUNCA modificar artefactos del core existente — solo agregar nuevos.
-- Si el artefacto duplica funcionalidad de uno existente en el core, RECHAZAR y sugerir `/swl:evolucionar` en su lugar.
-- Si `gh auth status` falla, DETENER inmediatamente — no intentar autenticación automática.
-- En `--dry-run`, el reporte debe ser completo y accionable sin crear ningún PR.
-- Los artefactos contribuidos mantienen su autoría original (campo `contributed-by`).
-- SIEMPRE verificar que el nombre del artefacto no colisione con uno existente en el core antes de crear el PR.
+---
+name: swl:contribuir
+description: Contribuye evoluciones de _userland/ al core de swl-ses creando un PR en GitHub. Filtra por dominio (solo ingeniería de software general), evalúa calidad con PluginEval (score ≥80 requerido) y crea el PR vía gh CLI. Flags: --skill=[nombre], --agente=[nombre], --dry-run.
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Agent"]
+---
+
+# /swl:contribuir — Contribuir evoluciones al core de swl-ses
+
+Eres el facilitador de contribuciones del sistema SWL. Tu responsabilidad es tomar evoluciones que un usuario creó en `_userland/` y, si pasan los filtros de calidad y dominio, crear un Pull Request contra el repositorio oficial de swl-ses.
+
+**Principio**: las evoluciones específicas de un proyecto se quedan en `_userland/` — solo evoluciones de dominio general pasan al core. Un skill de "configuración de Stripe para mi SaaS" no sube; un skill de "patrones de testing de APIs de pago" sí.
+
+## Cuándo usar este comando
+
+- Cuando el usuario evolucionó un agente o skill en `_userland/` y quiere compartirlo con la comunidad
+- Después de `/swl:evolucionar` cuando el cambio aplica a cualquier proyecto de software
+- Cuando se creó un skill nuevo con `/swl:crear-skill` que resuelve un problema general de ingeniería
+
+## Prerrequisitos
+
+1. **GitHub CLI (`gh`) autenticado** — verificar con `gh auth status`
+2. **Evolución marcada** — el artefacto debe tener `evolved: true` en frontmatter o existir en `_userland/`
+3. **Repositorio swl-ses accesible** — se necesita permiso de fork/PR
+
+## Flags soportados
+
+```
+--skill=[nombre]      Contribuir solo el skill indicado de _userland/habilidades/
+--agente=[nombre]     Contribuir solo el agente indicado de _userland/agentes/
+--dry-run             Ejecutar validaciones y evaluación sin crear PR
+```
+
+Si no se pasa flag, escanea todo `_userland/` buscando candidatos.
+
+## Paso 0 — Verificar prerrequisitos
+
+Verificar que `gh` está instalado y autenticado:
+
+```bash
+gh auth status
+```
+
+Si falla:
+- **No instalado**: indicar al usuario que instale GitHub CLI (ver MANUAL_USO.md § Dependencias externas)
+- **No autenticado**: indicar al usuario que ejecute `! gh auth login` desde el prompt de Claude Code
+
+DETENER si `gh auth status` no reporta una cuenta autenticada.
+
+## Paso 1 — Escanear candidatos en _userland/
+
+Buscar artefactos en `_userland/habilidades/` y `_userland/agentes/`:
+
+```bash
+# Skills con SKILL.md
+for dir in _userland/habilidades/*/; do
+  [ -f "$dir/SKILL.md" ] && echo "skill: $(basename $dir)"
+done
+
+# Agentes con .md
+for f in _userland/agentes/*.md; do
+  [ -f "$f" ] && echo "agente: $(basename $f .md)"
+done
+```
+
+Si se pasó `--skill` o `--agente`, filtrar a solo ese candidato.
+
+Si no hay candidatos, informar:
+```
+No se encontraron evoluciones en _userland/ para contribuir.
+Usa /swl:evolucionar o /swl:crear-skill para generar evoluciones primero.
+```
+
+## Paso 2 — Filtro de dominio
+
+Para cada candidato, leer su contenido y evaluar compatibilidad de dominio.
+
+**Pregunta de filtro**: *¿Le sirve esto a un ingeniero de software en cualquier proyecto de software?*
+
+**Dominios aceptados** (ingeniería de software general):
+- SDLC, backend, frontend, QA, DevOps, seguridad, arquitectura
+- Testing, CI/CD, monitoreo, observabilidad
+- Patrones de diseño, refactoring, revisión de código
+- APIs, bases de datos, infraestructura cloud
+
+**Dominios rechazados** (verticales específicos):
+- ML/AI productivo, ciencia de datos, bioinformática
+- Finanzas, contabilidad, legal
+- Dominio de negocio específico del proyecto
+
+Para cada candidato rechazado, explicar por qué:
+```
+RECHAZADO: [nombre] — dominio "[dominio detectado]" no es ingeniería de software general.
+Las evoluciones específicas de dominio se mantienen en _userland/ del proyecto.
+```
+
+## Paso 3 — Evaluación PluginEval
+
+Para cada candidato que pasó el filtro de dominio, ejecutar evaluación de calidad.
+
+Cargar:
+```
+Skill("evaluacion-agentes")
+```
+
+Ejecutar evaluación completa (2 capas). El score mínimo para contribuir es **80/100** (badge Oro).
+
+- **Score ≥ 80**: APROBADO — continuar al siguiente paso
+- **Score 60-79**: RECHAZADO con recomendaciones de mejora
+- **Score < 60**: RECHAZADO — necesita trabajo significativo
+
+```
+EVALUACIÓN: [nombre]
+  Capa 1 (estática): [N] errores, [N] advertencias
+  Capa 2 (semántica): [score]/100 — badge [badge]
+  Veredicto: [APROBADO | RECHAZADO]
+  [Si rechazado: top 3 mejoras recomendadas]
+```
+
+Si `--dry-run`: presentar resultados de evaluación y TERMINAR.
+
+## Paso 4 — Preparar contribución
+
+Para cada candidato aprobado:
+
+1. **Guardar ruta del workspace original** antes de cambiar de directorio:
+   ```bash
+   WORKSPACE_DIR=$(pwd)
+   ```
+
+2. **Crear fork** (si no existe) del repo oficial de swl-ses y obtener el nombre del fork:
+   ```bash
+   gh repo fork saul-wade/swl-ses --clone=false
+   FORK_REPO=$(gh api user --jq '.login')/swl-ses
+   ```
+
+3. **Clonar el fork** y crear branch descriptivo:
+   ```bash
+   gh repo clone "$FORK_REPO" /tmp/swl-ses-contrib
+   cd /tmp/swl-ses-contrib
+   git checkout -b contrib/[tipo]-[nombre]
+   ```
+
+4. **Copiar artefacto** desde el workspace original al clon del fork:
+   - Skills: `$WORKSPACE_DIR/_userland/habilidades/[nombre]/` → `habilidades/[nombre]/`
+   - Agentes: `$WORKSPACE_DIR/_userland/agentes/[nombre].md` → `agentes/[nombre].md`
+
+4. **Ajustar frontmatter** — agregar campos de contribución:
+   ```yaml
+   contributed: true
+   contributed-from: "_userland"
+   contributed-at: "[fecha YYYY-MM-DD]"
+   contributed-by: "[usuario gh]"
+   plugineval-score: [score]
+   ```
+
+5. **Registrar en plugin.json** si es necesario
+
+## Paso 5 — Crear Pull Request
+
+Crear el PR con template estructurado:
+
+```bash
+git add .
+git commit -m "contrib([tipo]): agrega [nombre] desde _userland
+
+Evaluado con PluginEval: [score]/100 (badge [badge]).
+Dominio: ingeniería de software general.
+
+Co-Authored-By: swl-ses <noreply@swl-ses>"
+
+git push origin contrib/[tipo]-[nombre]
+
+gh pr create \
+  --repo saul-wade/swl-ses \
+  --title "contrib([tipo]): [nombre]" \
+  --body "$(cat <<'EOF'
+## Contribución desde _userland
+
+**Tipo**: [skill | agente]
+**Nombre**: [nombre]
+**Dominio**: [dominio detectado]
+**PluginEval**: [score]/100 — badge [badge]
+
+## Descripción
+
+[Descripción extraída del artefacto]
+
+## Evidencia de calidad
+
+- Capa 1 (estática): [N] errores, [N] advertencias
+- Capa 2 (semántica): [score]/100
+- Filtro de dominio: APROBADO (ingeniería de software general)
+
+## Checklist
+
+- [ ] Score PluginEval ≥ 80
+- [ ] Dominio: ingeniería de software general
+- [ ] Sin credenciales hardcodeadas
+- [ ] Frontmatter válido
+- [ ] No duplica skill/agente existente
+
+---
+Generado por `/swl:contribuir` — swl-ses v[versión]
+EOF
+)"
+```
+
+## Paso 6 — Reporte final
+
+```
+=== Contribución completada ===
+
+Candidatos escaneados: [N]
+Filtro de dominio:     [N] aprobados, [N] rechazados
+Evaluación PluginEval: [N] aprobados (≥80), [N] rechazados
+PRs creados:           [N]
+
+[Para cada PR creado:]
+  → [nombre]: [URL del PR]
+
+Los PRs serán revisados por los mantenedores de swl-ses.
+```
+
+## Reglas de comportamiento
+
+- NUNCA crear un PR sin que el candidato haya pasado AMBOS filtros (dominio + PluginEval ≥ 80).
+- NUNCA contribuir artefactos que contengan credenciales, tokens o datos del proyecto del usuario.
+- NUNCA modificar artefactos del core existente — solo agregar nuevos.
+- Si el artefacto duplica funcionalidad de uno existente en el core, RECHAZAR y sugerir `/swl:evolucionar` en su lugar.
+- Si `gh auth status` falla, DETENER inmediatamente — no intentar autenticación automática.
+- En `--dry-run`, el reporte debe ser completo y accionable sin crear ningún PR.
+- Los artefactos contribuidos mantienen su autoría original (campo `contributed-by`).
+- SIEMPRE verificar que el nombre del artefacto no colisione con uno existente en el core antes de crear el PR.

package/comandos/swl/ejecutar-fase.md

@@ -4,20 +4,41 @@ description: Recibe el número de una fase y la implementa siguiendo el PLAN.md.
 allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
 ---
 
-# /swl:ejecutar-fase <n> — Ejecutar implementación de una fase
+# /swl:ejecutar-fase <n> [--iterative] — Ejecutar implementación de una fase
 
 Eres el coordinador de ejecución SWL. Orquestas la implementación real del código para una fase, delegando al agente implementador-swl, verificando cada slice y manteniendo el estado del proyecto actualizado.
 
 ## Uso
 
 ```
-/swl:ejecutar-fase 1
-/swl:ejecutar-fase 2
+/swl:ejecutar-fase 1                # modo default — oleadas paralelas
+/swl:ejecutar-fase 2 --iterative    # modo iterativo — 1 tarea, review per-task, auto-debug
 ```
 
+### Cuándo usar `--iterative` (modo opt-in)
+
+Activar el flag `--iterative` cuando:
+
+- La fase tiene **dependencias secuenciales fuertes** entre tareas.
+- El módulo es **crítico** (dinero, permisos, datos irreversibles) y cada tarea merece revisión adversarial inmediata.
+- La fase tiene **>12 tareas** y el modo paralelo arriesga acumular deuda silenciosa.
+- El usuario pide explícitamente "tarea por tarea con revisión".
+
+NO usar `--iterative` para fases pequeñas (<5 tareas) o cuando las tareas son
+independientes y de bajo riesgo — el overhead per-task supera el beneficio.
+
 ## Paso 0 — Carga de habilidades
 
-Carga obligatoria:
+Si `--iterative` está presente, carga:
+```
+Skill("ejecutar-task-iterativo")
+```
+
+El skill iterativo redirige el flujo: 1 tarea por iteración, contexto fresco
+por implementer, review task-local con `protocolo-revision-swl`, auto-debug
+en BLOCKED con `depurador-swl`, y commits atómicos estrictos por tarea.
+
+Si NO hay `--iterative`, carga el flujo default:
 ```
 Skill("ejecutar-fase")
 ```
@@ -31,6 +52,14 @@ Luego carga habilidades específicas del stack detectado en PLAN.md o PROYECTO.m
 - Autenticación: `Skill("auth-patrones")`
 - Siempre: `Skill("manejo-errores")`
 
+### Si `--iterative` está activo
+
+Tras cargar `ejecutar-task-iterativo`, sigue el protocolo definido ahí
+(loop per-task con Pasos 1-8 internos del skill). El resto de pasos de
+este comando se delegan al skill iterativo. Saltar los Pasos 2-7 de este
+comando. El Paso 8 (Reporte final) y Reglas de comportamiento siguen
+aplicando en ambos modos.
+
 ## Paso 1 — Verificación de prerrequisitos
 
 Verifica en orden:

package/comandos/swl/metricas.md

@@ -21,6 +21,7 @@ costo estimado, herramientas más usadas y estado del presupuesto configurado.
 ```
 /swl:metricas             — Resumen de métricas de la sesión
 /swl:metricas detalle     — Desglose completo por herramienta y timeline
+/swl:metricas fases       — Progreso de fases del proyecto desde feature-list.json
 /swl:metricas historico   — Abre el dashboard histórico multi-sesión (alias de /swl:dashboard)
 ```
 
@@ -246,6 +247,77 @@ EOF
 
 ---
 
+## Subcomando: `fases` — Progreso de fases del proyecto
+
+Si el usuario invoca `/swl:metricas fases`, muestra el estado actual de las
+fases del proyecto leyendo el JSON derivado de `HOJA-RUTA.md`.
+
+### Generación y lectura del estado
+
+```bash
+# Regenerar el JSON desde HOJA-RUTA.md (fuente de verdad markdown)
+node scripts/derivar-feature-list.js
+
+# Leer el JSON generado en .planning/feature-list.json
+cat .planning/feature-list.json | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+t = data['totales']
+total = t['fases'] or 1
+pct = (t['completadas'] / total) * 100
+
+print(f\"\\nSWL — Progreso de fases del proyecto\")
+print('─' * 60)
+print(f\"  Total de fases:        {t['fases']}\")
+print(f\"  Completadas:           {t['completadas']}  ({pct:.0f}%)\")
+print(f\"  En progreso:           {t['en_progreso']}\")
+print(f\"  Pendientes:            {t['pendientes']}\")
+print(f\"  Bloqueadas:            {t['bloqueadas']}\")
+print(f\"  Spec lista:            {t['spec_listas']}\")
+print('─' * 60)
+print()
+for f in data['fases']:
+    estado = f['estado']
+    marca = {'completado': '✓', 'en_progreso': '◐', 'pendiente': '○',
+             'bloqueado': '✗', 'spec_listo': '◔'}.get(estado, '?')
+    nombre = f['nombre'][:48]
+    art = f.get('artefactos') or {}
+    plan = ' [PLAN]' if art.get('plan_md') else ''
+    resumen = ' [RESUMEN]' if art.get('resumen_md') else ''
+    print(f\"  {marca} Fase {f['numero']:>2}: {nombre:<50}{plan}{resumen}\")
+print()
+print(f\"  Fuente: {data['fuente']}  ·  Generado: {data['generado_en']}\")
+"
+```
+
+### Lo que se reporta
+
+- **Totales**: cuántas fases hay y cuántas en cada estado canónico (`completado`,
+  `en_progreso`, `pendiente`, `bloqueado`, `spec_listo`).
+- **Lista de fases** con marca visual de estado y artefactos presentes
+  (`[PLAN]` si existe `0N-PLAN.md`, `[RESUMEN]` si existe `0N-RESUMEN.md`).
+- **Timestamp** de generación para detectar staleness.
+
+### Cuándo usar
+
+- Antes de retomar trabajo en una fase, para ver el estado actualizado.
+- Al cerrar una sesión productiva, para verificar progreso vs HOJA-RUTA.md.
+- Para auditoría programática (consumir el JSON desde un hook o dashboard externo).
+
+### Detección de drift
+
+Si `HOJA-RUTA.md` se modifica pero `feature-list.json` no se regenera, los datos
+quedan desactualizados. Para verificar:
+
+```bash
+node scripts/derivar-feature-list.js --check
+# exit 0 = sincronizado, exit 2 = drift detectado
+```
+
+`/swl:metricas fases` siempre regenera primero, así que ve estado fresco.
+
+---
+
 ## Subcomando: `historico`
 
 Si el usuario invoca `/swl:metricas historico`, redirigir inmediatamente a: