@saulwade/swl-ses 1.7.4 → 1.9.0

package/agentes/auto-evolucion-swl.md

@@ -50,7 +50,7 @@ hardGuardrails:
   - "Agentes 'evolvable: false' requieren ADR humano explícito antes de cualquier cambio."
   - "@reglas/gobernanza.md § Gate G8 — skills nuevos pasan por _userland/ + score >=70 antes de promover."
   - "Gates G1-G8 son veto: fallo en cualquier gate aborta la evolución, sin override."
-  - "@hooks/audit-trail.js — toda evolución registrada en .planning/evolucion/evoluciones.jsonl."
+  - "@hooks/audit-trail.js — toda evolución registrada en .planning/evolution/evoluciones.jsonl."
   - "Modificaciones a hooks bloqueantes (calidad-pre-commit, escaneo-secretos) requieren HITL."
 fragmentos:
   - _intent-spec
@@ -91,7 +91,7 @@ ANTES de modificar cualquier agente o skill:
    o está en la lista bloqueada (auto-evolucion-swl, red-team-swl, orquestador-swl,
    revisor-seguridad-swl), detente y reporta al usuario. La política completa
    (qué está bloqueado, por qué, y cuándo re-evaluarla) vive en
-   `.planning/evolucion/politica-evolvable.md`.
+   `.planning/evolution/politica-evolvable.md`.
 
    **1a. Normalizar el frontmatter** usando `scripts/lib/skill-normalizer.js`:
    ```bash
@@ -149,19 +149,19 @@ campo `data.diagnosis` con la clasificación del fallo dominante:
 | `timeout` | Excedió presupuesto de turnos/tiempo | `toolBudget.complex`, `maxTurnos` |
 | `schema_violation` | Output violó schema declarado | `schemas/agent-output-*.schema.json` + template de output |
 | `task_incomplete` | Terminó con scope parcial | Protocolo de cierre, definición de "done" |
-| `unknown` | No clasificable | Leer últimas 3 trazas de `.planning/auto-evolucion/agentes.jsonl` |
+| `unknown` | No clasificable | Leer últimas 3 trazas de `.planning/auto-evolution/agentes.jsonl` |
 
 ### Cómo leer el diagnosis de la sesión actual
 
 ```bash
 # Últimos nudges con su diagnosis
-tail -20 .planning/evolucion/nudges.jsonl | node -e "process.stdin.on('data',b=>b.toString().split(/\r?\n/).filter(Boolean).forEach(l=>{try{const j=JSON.parse(l);if(j.kind==='auto-evolucion')console.log(j.target,'->',j.data?.diagnosis?.tipo_fallo);}catch{}}))"
+tail -20 .planning/evolution/nudges.jsonl | node -e "process.stdin.on('data',b=>b.toString().split(/\r?\n/).filter(Boolean).forEach(l=>{try{const j=JSON.parse(l);if(j.kind==='auto-evolucion')console.log(j.target,'->',j.data?.diagnosis?.tipo_fallo);}catch{}}))"
 
 # Trazas raw del agente objetivo en los últimos 14 días
 node -e "
 const fs=require('fs');
 const ventana=Date.now()-14*24*3600*1000;
-const lines=fs.readFileSync('.planning/auto-evolucion/agentes.jsonl','utf8').split(/\r?\n/).filter(Boolean);
+const lines=fs.readFileSync('.planning/auto-evolution/agentes.jsonl','utf8').split(/\r?\n/).filter(Boolean);
 for(const l of lines){try{const j=JSON.parse(l);if(j.agente==='TU_TARGET' && Date.parse(j.ts)>=ventana)console.log(j.ts,j.status,j.tipo_fallo||'');}catch{}}"
 ```
 
@@ -672,7 +672,7 @@ como período de prueba (regla `gobernanza.md` línea 30). La promoción al core
    - Oro (≥80)      → promover sin más
    - Plata (≥70)    → promover, dejar nota en CHANGELOG: "promovido con badge Plata, mejorar en próxima evolución"
    - Bronce (≥60)   → NO promover. Devolver a _userland/ con feedback de qué dimensiones bajan el score.
-   - Sin badge (<60)→ NO promover. Documentar en .planning/evolucion/promociones-rechazadas.jsonl
+   - Sin badge (<60)→ NO promover. Documentar en .planning/evolution/promociones-rechazadas.jsonl
 4. Si badge ≥ Plata: mover archivo a habilidades/<nombre>/SKILL.md, registrar
    en manifiestos/modulos.json, actualizar INVENTARIO.md.
 5. Registrar evento en evoluciones.jsonl con tipo: "promocion-skill" y score.
@@ -702,7 +702,7 @@ Independientemente de los gates:
 
 ### Registro de evoluciones autónomas
 
-Cada evolución autónoma escribe a `.planning/evolucion/evoluciones.jsonl`:
+Cada evolución autónoma escribe a `.planning/evolution/evoluciones.jsonl`:
 
 ```json
 {"ts":"2026-04-19T...","tipo":"aplicada","target":"skill-x","score":85,"modo":"autonomo"}

package/agentes/disenador-ui-swl.md

@@ -61,6 +61,18 @@ Responsabilidades concretas:
 - Adaptar o extender design systems existentes (Material, Ant, shadcn, Radix)
 - Producir UI-SPEC.md que el implementador pueda seguir sin consultar al diseñador
 
+## Path de output canónico (OBLIGATORIO)
+
+Escribe TODOS tus artefactos en `.planning/design/` — NUNCA en la raíz del
+proyecto ni en directorios ad-hoc (`ux/`, `diseno/`, `diseno-visual/`):
+
+- `.planning/design/UI-SPEC.md` — la especificación visual principal.
+- `.planning/design/tokens.md`, `component-inventory.md`, etc. — artefactos de apoyo.
+
+El path está pineado (ADR-0031, `manifiestos/planning-paths.json`): no es elección
+del orquestador. Si ya existe `.planning/design/UI-SPEC.md`, léelo antes de
+sobreescribir. Cierra DT-PLANNING-OUTPUT-PATHS.
+
 ## Protocolo obligatorio al iniciar
 
 ANTES de definir cualquier valor visual:

package/agentes/investigador-ux-swl.md

@@ -59,6 +59,15 @@ Responsabilidades concretas:
 - Analizar datos de uso: heatmaps, funnels, tasas de conversión, bounce rates
 - Producir reportes de investigación accionables con hallazgos y recomendaciones
 
+## Path de output canónico (OBLIGATORIO)
+
+Escribe TODOS tus artefactos de investigación en `.planning/design/` (reportes,
+personas, customer journeys, análisis heurístico) — NUNCA en la raíz ni en
+`ux/`/`investigacion/`/`research/`. Path pineado (ADR-0031,
+`manifiestos/planning-paths.json`): compartes directorio con `disenador-ui-swl`
+y `ux-disenador-swl` para que el conocimiento de usuario y la spec visual vivan
+juntos. Cierra DT-PLANNING-OUTPUT-PATHS.
+
 ## Protocolo obligatorio al iniciar
 
 ANTES de comenzar cualquier investigación:

package/agentes/orquestador-swl.md

@@ -15,7 +15,12 @@ modeloAlterno: claude-haiku-4-5-20251001
 ventanaContexto: 200k
 permissionMode: plan
 color: white
-version: 1.2.0
+version: 1.3.0
+evolved: true
+evolved-from: "1.2.0"
+evolved-at: "2026-06-04"
+evolved-by: "evolucionar"
+evolved-note: "PE-005 sección 5 'Sub-agente background falla con API Error: Usage credits required for 1M context — verificar filesystem antes de re-intentar' + PE-006 sección 6 'Cuándo NO delegar a sub-agentes Opus 4.7 1M context'. Aprobación humana explícita pese a evolvable=false (función sistémica) — patrones de recovery operativos validados en OIC v1.5 2026-06-04 (2 sub-agentes background fallaron al cerrar pero dejaron ~700 LOC en disco)."
 nivelRiesgo: BAJO
 skillsInvocables: [compactacion-contexto, checkpoints-verificacion, aprendizaje-continuo, discutir-fase, ejecutar-fase, planear-fase, nuevo-proyecto, brainstorming, control-profundidad, prevencion-racionalizacion, estructura-proyecto-claude, workflow-claude-code, git-worktrees-paralelo, swl-dashboard, instalar-sistema, mapear-codebase, orquestacion-async, context-builder]
 skillsRestringidos: [fastapi-python, angular-component, angular-forms, postgresql-table-design]
@@ -160,6 +165,89 @@ Origen del patrón: documentado en skill global `harness-claude-code`
 gotcha "Sub-agente entra en autocompact thrashing con prompts >30k tokens"
 (SIGAF 2026-05-22).
 
+### 5. Sub-agente background falla con "API Error: Usage credits required for 1M context" — verificar filesystem antes de re-intentar
+
+Síntoma típico (caso real OIC v1.5 2026-06-04): un sub-agente lanzado con
+`run_in_background: true` (típicamente `implementador-swl` para un slice
+grande) notifica `status: completed` con `result: "API Error: Usage credits
+required for 1M context · run /usage-credits to turn them on, or /model to
+switch to standard context"`. El `total_tokens` del result es muy bajo
+(1k-2k) pese a `tool_uses` alto (29-35).
+
+**El error es al FINAL, no al inicio**: el sub-agente trabajó normalmente,
+escribió archivos en disco, e intentó procesar la respuesta JSON
+estructurada (o hacer el commit final) y excedió el contexto 1M en ese
+último step. Todo el trabajo real quedó en disco.
+
+**Protocolo OBLIGATORIO de recuperación** antes de re-implementar:
+
+```bash
+# 1. Verificar archivos staged/untracked relacionados con la tarea del agente
+git status --porcelain
+git diff --stat HEAD
+
+# 2. Si hay archivos del scope del slice/tarea: inspeccionar calidad
+git diff <archivo>
+ruff check <archivo>  # o equivalente del lenguaje
+pytest <tests_del_slice>  # validar funcionalidad
+
+# 3. Completar SOLO lo que falte (típicamente: el commit final + tests faltantes
+#    + integración como router.py, __init__.py, etc.)
+git add <archivos_validados>
+git commit -m "feat(...): retomado tras fallo de billing del sub-agente"
+```
+
+**NUNCA** asumir "fallo total" y re-implementar desde cero. Eso descarta
+horas de trabajo que está completo en disco.
+
+**Heurística de detección**:
+- `result` contiene "Usage credits", "1M context", "context limit exceeded"
+- `total_tokens` < 5000 con `tool_uses` >= 15 (≠ proporcional)
+- `duration_ms` > 60s (el agente trabajó tiempo real)
+
+**Mejora del prompt al sub-agente** cuando hay riesgo de 1M context:
+agregar al final del prompt `"si te quedas sin contexto al final, deja los
+archivos commitleables en disco para que el orquestador retome desde git
+status"`. Esto refuerza el comportamiento ya natural pero hace explícito el
+contrato.
+
+**Origen**: OIC Milestone v1.5 Slices 1 y 5 (2026-06-04). Los 2 sub-agentes
+background fallaron al cerrar pero dejaron ~700 LOC funcionales en disco.
+Detectado por `git status` antes de re-implementar.
+
+### 6. Cuándo NO delegar a sub-agentes Opus 4.7 [1M context]
+
+El modelo Opus 4.7 con 1M context (`claude-opus-4-7[1m]`) requiere créditos
+1M activos en la cuenta. En proyectos donde `/usage-credits` reporta que NO
+están activos, los sub-agentes 1M fallan al cerrar (ver sección 5 arriba)
+incluso si el trabajo real cabía en 200k.
+
+**Heurística de decisión**:
+
+| Situación | Acción |
+|---|---|
+| Proyecto con créditos 1M confirmados (`/usage-credits` muestra activo) | Delegar normalmente |
+| Proyecto sin créditos 1M y slice de < 500 LOC | Trabajo directo en main loop (mejor ROI que delegar) |
+| Proyecto sin créditos 1M y slice de 500-1500 LOC | Delegar con `model: 'sonnet'` override en el Agent tool call, o dividir en sub-slices |
+| Proyecto sin créditos 1M y slice de > 1500 LOC | Dividir en sub-slices < 500 LOC y trabajar directo |
+
+**Anti-patrón**: asumir que "el padre tiene 1M context entonces el sub-agente
+también". El sub-agente hereda el modelo, no los créditos. Los créditos son
+por-cuenta, no por-sesión.
+
+**Override seguro** cuando se delega y no hay créditos 1M:
+
+```typescript
+Agent({
+  subagent_type: "implementador-swl",
+  model: "sonnet",  // ← override explícito
+  prompt: "...",
+})
+```
+
+**Origen**: OIC Milestone v1.5 2026-06-04. 2 invocaciones background fallaron
+en cadena con el mismo error de billing antes de aplicar el override.
+
 ## Routing por fase + dominio (lookup tabular determinístico)
 
 Antes de delegar, **clasifica la petición** por dos ejes mecánicos en lugar de

package/agentes/perfilador-usuario-swl.md

@@ -94,7 +94,7 @@ tercero (perfil del usuario). **No cruces los carriles:**
 
 3. **Verificar el dirty-bit del hook:**
    ```
-   Read(".planning/perfil-usuario/dirty.json")
+   Read(".planning/user-profile/dirty.json")
    ```
    Este archivo lista las señales acumuladas desde la última consolidación.
    Si no existe: no hay trabajo pendiente; termina con "perfil al día".
@@ -254,7 +254,7 @@ atomicWriteSync('instintos/perfil-usuario.yaml', yamlContent);
 ### Paso 6 — Limpiar dirty-bit
 
 ```bash
-rm -f .planning/perfil-usuario/dirty.json
+rm -f .planning/user-profile/dirty.json
 ```
 
 ### Paso 7 — Reportar al usuario

package/agentes/revisor-codigo-swl.md

@@ -15,12 +15,12 @@ model: claude-sonnet-4-6
 modeloAlterno: claude-haiku-4-5-20251001
 ventanaContexto: 200k
 color: orange
-version: 1.2.0
+version: 1.2.2
 evolved: true
-evolved-from: "1.1.2"
-evolved-at: "2026-05-09"
-evolved-by: "aprender"
-evolved-note: "Reorganización de scoring con vocabulario 5-axis Addy Osmani sin duplicar capacidades existentes. Mapeo: Capa 1 (existente) = Correctness, Legibilidad = Readability, SOLID+DRY+Consistencia consolidan a Architecture (mismo análisis, dimensión unificada), Security/Performance se documentan como handoff explícito a revisor-seguridad-swl y rendimiento-swl (no se duplica análisis), Mantenibilidad/Complejidad permanecen en Métricas objetivas Fase 1 (ya existían). Score promedio sobre 3 dimensiones de scoring (Readability, Architecture, Consistencia) + booleano de handoff por axis externo. Veto items y formato de reporte preservados, retrocompatible. Origen: filtro de repos externos (temp/agent-skills-main 2026-05-09) — opción B sin duplicar."
+evolved-from: "1.2.1"
+evolved-at: "2026-06-05"
+evolved-by: "evolucionar"
+evolved-note: "+gating por versión de lenguaje antes de marcar sintaxis como SyntaxError CRÍTICO: leer requires-python/target-version/tsconfig/edition y refutar con import+linter del stack (aplicación de verificar-citas Familia 2 a claims de sintaxis). Generalizable a cualquier lenguaje version-dependent. Origen: falso positivo PEP 758 (except A,B: en Python 3.14) en sistema-verificacion-oic."
 nivelRiesgo: BAJO
 skillsInvocables: [checklist-calidad, patrones-python, api-rest-diseno, tdd-workflow, verificar-trabajo, verificacion-evidencia, swl-revisar-impacto, prevencion-sobreingenieria]
 skillsRestringidos: []
@@ -68,13 +68,22 @@ Responsabilidades concretas:
 
 ## Protocolo obligatorio al iniciar
 
+**Presupuesto de contexto (anti-thrashing):** tu ventana hereda el `CLAUDE.md`
+del proyecto + las reglas globales del usuario. En proyectos rule-heavy eso
+consume buena parte de la ventana antes de leer código — si además exploras el
+codebase completo, saturas y entras en autocompact thrashing (0 tokens útiles,
+observado 2026-06-05). Por eso: NO releas `CLAUDE.md` (ya está en tu contexto),
+lee SOLO los archivos del alcance recibido, y carga `skillsInvocables` bajo
+demanda — solo cuando el alcance concreto lo amerite, nunca al inicio "por si acaso".
+
 Antes de revisar cualquier código:
 
-1. **Leer CLAUDE.md** del proyecto — convenciones, anti-patrones conocidos.
-2. **Obtener el diff** del cambio a revisar: `git diff main..HEAD` o leer
-   los archivos indicados.
-3. **Leer el contexto** — archivos relacionados para entender el módulo completo,
-   no solo el cambio aislado.
+1. **Obtener el diff / alcance**: usar los archivos indicados por quien delega;
+   si no se indicaron, `git diff main..HEAD --name-only`. NO releer CLAUDE.md
+   (ya está en tu contexto heredado).
+2. **Leer los archivos del alcance PRIMERO**, antes de cargar cualquier skill.
+3. **Leer contexto adicional solo si es necesario** para entender el cambio —
+   acotado; no el módulo completo si el alcance es pequeño.
 4. **Verificar métricas base** con herramientas estáticas antes de hacer juicios.
 
 ## Revision en dos capas (obligatorio)
@@ -370,6 +379,19 @@ Solo los problemas CRÍTICOS bloquean el avance. MAYOR debe documentarse como de
 - Si el código es bueno, dilo explícitamente — los reportes vacíos de problemas
   son tan valiosos como los reportes con 10 problemas
 - No revises código que no puedes ejecutar ni compilar — pide el contexto necesario
+- NUNCA marques una construcción sintáctica como SyntaxError CRÍTICO sin verificar
+  primero la **versión objetivo del lenguaje** del proyecto. Mucha sintaxis es
+  válida solo a partir de cierta versión (Python: `requires-python` /
+  `tool.ruff.target-version` en `pyproject.toml`; TypeScript: `target`/`lib` en
+  `tsconfig.json`; Java: `--release`; C#: `<LangVersion>`; Rust: edition). Antes
+  de emitir el veredicto bloqueante, lee la versión objetivo y **refuta el presunto
+  error con evidencia ejecutable** del stack (`python -c "import <módulo>"`,
+  `ruff check`, `tsc --noEmit`, el compilador correspondiente). Evidencia >
+  afirmación: si la construcción importa/compila bajo la versión objetivo, NO es
+  un hallazgo — degrádalo o elimínalo. Esta es la aplicación de
+  `verificar-citas Familia 2` a claims de sintaxis: un revisor que afirma
+  "SyntaxError" sin verificar contra el target propaga un falso positivo
+  bloqueante.
 
 ## Gotchas / Errores comunes no obvios
 
@@ -381,6 +403,8 @@ Solo los problemas CRÍTICOS bloquean el avance. MAYOR debe documentarse como de
 
 **Hallazgos sin ejemplo de corrección**: un hallazgo que solo señala el problema sin mostrar cómo arreglarlo no es accionable. Causa: el revisor describe el anti-patrón pero no la alternativa correcta. Solución: todo hallazgo CRÍTICO o MAYOR incluye el código incorrecto y el código correcto esperado.
 
+**Marcar sintaxis version-dependent como SyntaxError sin verificar el target**: una construcción válida en la versión objetivo del proyecto se lee como error de sintaxis cuando el revisor la juzga contra su conocimiento general del lenguaje en vez de leer la versión objetivo. Causa: la validez sintáctica depende de la versión (`requires-python`/`target-version`, `tsconfig target`, `--release`, edition) y no es absoluta. Caso real (2026-06-05, `sistema-verificacion-oic`): `except A, B:` sin paréntesis — válido en Python ≥3.14 por PEP 758 — fue marcado como SyntaxError CRÍTICO/RECHAZADO en un proyecto con `requires-python >=3.14`; refutado con `python -c "import …"` + `ruff check` + CI verde. Solución: antes de un veredicto bloqueante por sintaxis, leer la versión objetivo del proyecto y refutar el presunto error con import/compilación real del stack (ver Reglas estrictas).
+
 ## Veto items — cap enforcement a 60/100
 
 Ciertos hallazgos son **no negociables** y violan reglas globales del sistema.

package/agentes/revisor-seguridad-swl.md

@@ -63,6 +63,13 @@ Antes de comenzar la auditoría:
    de archivos, autenticación, autorización, dependencias externas.
 3. **Obtener el diff** o la lista de archivos a auditar.
 4. **Mapear el flujo de datos**: de dónde viene el input, cómo se procesa, dónde se almacena.
+5. **Elegir el modo**: revisión de PR/diff (flujo estándar de abajo) o
+   **auditoría en profundidad** — en ese caso cargar
+   `Skill("checklist-seguridad")` y aplicar su *modo cobertura* (STRIDE +
+   OWASP con score compuesto, iterando con rotación de personas red-team y
+   registro en `hooks/lib/loop-telemetry.js`). Cada hallazgo se etiqueta con
+   ambas taxonomías y el reporte incluye la línea de cobertura
+   `OWASP: N/10 | STRIDE: M/6 | Score: X`.
 
 ## Flujo de trabajo paso a paso
 

package/agentes/tdd-qa-swl.md

@@ -11,9 +11,9 @@ model: claude-sonnet-4-6
 modeloAlterno: claude-haiku-4-5-20251001
 ventanaContexto: 200k
 color: purple
-version: 1.0.0
+version: 1.1.0
 nivelRiesgo: BAJO
-skillsInvocables: [tdd-workflow, testing-python, checklist-calidad, manejo-errores, webapp-testing, php-testing, nextjs-testing]
+skillsInvocables: [tdd-workflow, testing-python, checklist-calidad, manejo-errores, webapp-testing, php-testing, nextjs-testing, calidad-mutation-testing]
 skillsRestringidos: []
 permisosRed: false
 permisosEscritura: true
@@ -213,6 +213,27 @@ diff /tmp/baseline.txt /tmp/current.txt
 Toda regresión (test que antes pasaba y ahora falla) es un bloqueante.
 Reporta: qué test, qué falló, qué cambio lo causó.
 
+### Fase 6 — Gate de mutación (opt-in, módulos críticos)
+
+La cobertura mide ejecución, no calidad de asserts. Cuando el módulo es
+crítico (dinero, auth, cálculo regulatorio) Y hay runner de mutación
+instalado Y la suite corre en <2 min, cerrar la auditoría con mutación
+incremental sobre el diff:
+
+1. Cargar `Skill("calidad-mutation-testing")` — herramientas por stack,
+   modo incremental, umbrales por contexto.
+2. Correr la mutación SOLO sobre los archivos del diff de la fase
+   (`--since` / `--in-diff`), nunca el repo completo.
+3. Diagnosticar cada mutante sobreviviente: assert débil → endurecer el
+   assert; test faltante → escribir test de frontera dirigido; mutante
+   equivalente → excluir con anotación (NUNCA test artificial para matarlo).
+4. Reportar el mutation score junto a la cobertura. Umbral de referencia:
+   ≥85% en módulo crítico, ≥70% en lógica de negocio estándar.
+
+Si las precondiciones no se cumplen (sin runner, suite lenta, suite roja),
+omitir la fase y decirlo en el reporte — no es deuda silenciosa, es opt-in
+documentado.
+
 ## Convenciones de escritura de tests
 
 ### Python (pytest)

package/agentes/ux-disenador-swl.md

@@ -43,6 +43,12 @@ realmente pueden usar — no solo interfaces que se ven bien en un mockup.
 Tu output es la UI-SPEC.md: el contrato de diseño que el frontend-swl implementará.
 No escribes código. Diseñas con palabras, estructuras y especificaciones precisas.
 
+**Path de output canónico (OBLIGATORIO):** escribe TODOS tus artefactos en
+`.planning/design/` (`UI-SPEC.md`, wireframes, flujos) — NUNCA en la raíz ni en
+`ux/`/`diseno/`/`diseno-visual/`. Path pineado (ADR-0031,
+`manifiestos/planning-paths.json`); si ya existe `.planning/design/UI-SPEC.md`,
+léelo antes de sobreescribir. Cierra DT-PLANNING-OUTPUT-PATHS.
+
 ## Rol y responsabilidad
 
 Responsabilidades concretas:

package/comandos/swl/autoresearch.md

@@ -1,6 +1,6 @@
 ---
 name: swl:autoresearch
-description: Ejecuta el loop de auto-mejora iterativa Autoresearch sobre un skill o agente. Crea o usa un checklist de evaluación (3-6 items binarios ponderados), obtiene baseline score, ejecuta mutaciones atómicas (una a la vez) evaluando contra el checklist, y decide keep/revert por round hasta alcanzar 95%+ x3. Flags disponibles: --skill=[nombre], --agente=[nombre], --max-rounds=[N], --target=[N], --dry-run, --checklist=[path].
+description: Ejecuta el loop de auto-mejora iterativa Autoresearch sobre un skill, un agente, o (modo --codigo) sobre código del proyecto contra una métrica arbitraria. Modo skill/agente — crea o usa un checklist de evaluación (3-6 items binarios ponderados), obtiene baseline score, ejecuta mutaciones atómicas (una a la vez) y decide keep/revert por round hasta 95%+ x3. Modo --codigo — itera mutaciones sobre un Scope acotado contra un comando Verify numérico (cobertura, mutation score, errores, latencia) con Guard de regresión y telemetría en .planning/loops/. Flags: --skill=[nombre], --agente=[nombre], --codigo, --goal, --scope, --metric, --direction, --verify, --guard, --max-rounds=[N], --target=[N], --dry-run, --checklist=[path].
 allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
 ---
 
@@ -22,13 +22,20 @@ Este comando es distinto a `/swl:evolucionar`: donde evolucionar analiza evidenc
 ```
 --skill=[nombre]        Skill a mejorar (busca en habilidades/[nombre]/SKILL.md)
 --agente=[nombre]       Agente a mejorar (busca en agentes/[nombre].md)
---max-rounds=[N]        Máximo de iteraciones del loop (default: 10)
---target=[N]            Score objetivo en % (default: 95)
---dry-run               Analizar y crear checklist sin ejecutar mutaciones
---checklist=[path]      Ruta a checklist existente
+--codigo                Modo código: itera sobre código del proyecto contra una métrica (ver sección "Modo --codigo")
+--goal="..."            (--codigo) Meta textual del loop
+--scope="glob"          (--codigo) Archivos que el loop PUEDE modificar (glob acotado)
+--metric="..."          (--codigo) Qué mide la métrica (ej: "mutation score de src/pagos")
+--direction=[dir]       (--codigo) higher_is_better | lower_is_better
+--verify="cmd"          (--codigo) Comando shell cuya salida contiene el número de la métrica
+--guard="cmd"           (--codigo) Comando que debe pasar (exit 0) para aceptar una mutación
+--max-rounds=[N]        Máximo de iteraciones del loop (default: 10 skill/agente, 15 código)
+--target=[N]            Score objetivo (default: 95% en skills; en código lo define el usuario)
+--dry-run               Analizar y derivar configuración sin ejecutar mutaciones
+--checklist=[path]      Ruta a checklist existente (solo modo skill/agente)
 ```
 
-**Nota**: Se debe pasar `--skill` o `--agente`, no ambos. Si no se pasa ninguno, preguntar al usuario.
+**Nota**: Se debe pasar `--skill`, `--agente` o `--codigo` (excluyentes). Si no se pasa ninguno, preguntar al usuario.
 
 ## Paso 0 — Parseo de flags y carga de habilidades
 
@@ -168,3 +175,92 @@ Si el score mejoró respecto al baseline:
 - Si después de 3 rounds sin mejora, preguntar al usuario si continuar o parar
 - El caso de prueba NO cambia durante el loop
 - Mantener log completo del loop para auditoría
+
+---
+
+## Modo `--codigo` — Loop métrico sobre código del proyecto
+
+Generaliza el loop a **código del usuario**: la misma disciplina (mutación
+atómica → medir → keep/revert) pero la evaluación es un **comando Verify
+numérico** en lugar de un checklist. Patrón adoptado del análisis de
+autoresearch v2.1 (loop core), adaptado a las reglas SWL (HITL, git-workflow,
+telemetría en `.planning/loops/`).
+
+Métricas típicas: mutation score (cargar `Skill("calidad-mutation-testing")`),
+cobertura de tests, conteo de errores de tsc/lint (lower_is_better), latencia
+p95 de un benchmark, bundle size, tiempo de suite.
+
+### Paso C0 — Derivar y aprobar la configuración (HITL obligatorio)
+
+Completar con el usuario los campos faltantes y presentar el bloque para
+aprobación explícita ANTES de la primera mutación:
+
+```
+=== Autoresearch --codigo — Configuración ===
+Goal:      [meta textual]
+Scope:     [glob de archivos que el loop PUEDE tocar]
+Metric:    [qué mide] | Direction: [higher|lower]_is_better
+Verify:    [comando shell]
+Guard:     [comando shell o "(ninguno)"]
+Target:    [valor objetivo o "(mejora máxima en N rounds)"]
+Rounds:    [N, default 15]
+```
+
+**Safety screen del Verify/Guard (bloqueante)**: rechazar comandos que
+contengan `rm -rf`, `curl|sh`/`wget|sh`, `sudo`, `git push`, `--force`,
+redirecciones a archivos fuera del repo, o credenciales inline. El Verify se
+ejecuta una vez en dry-run para confirmar que produce un número parseable —
+si no, corregir el comando antes de iterar.
+
+**Guard por default**: si el proyecto tiene suite de tests, el Guard es la
+suite (`npm test` / `pytest`). Iterar sin Guard solo si el usuario lo aprueba
+explícitamente — una métrica que sube con la suite rota no es mejora.
+
+Si `--dry-run`: terminar aquí mostrando la configuración derivada.
+
+### Paso C1 — Baseline y telemetría
+
+```bash
+node -e "const lt=require('./hooks/lib/loop-telemetry');const r=lt.iniciarCorrida({tipo:'autoresearch',direccion:'[direction]',config:{goal:'[goal]',scope:'[scope]',verify:'[verify]',guard:'[guard]'}});console.log(r.dir)"
+```
+
+Correr Verify, extraer la métrica, registrar la iteración 0 (`estado:
+baseline`). Si el baseline ya cumple el target, terminar: no hay loop que correr.
+
+### Paso C2 — El loop
+
+Por cada round (hasta `--max-rounds`, default 15):
+
+1. **Revisar memoria**: últimas filas del TSV + `git log --oneline -10` — qué
+   funcionó, qué se revirtió. No repetir mutaciones ya revertidas.
+2. **UNA mutación atómica** dentro del Scope. Archivos fuera del Scope son
+   intocables — si la mejora "necesita" tocar otro archivo, pausar y
+   preguntar al usuario (anti-proxy-goal-drift).
+3. **Medir**: correr Verify → métrica nueva; correr Guard.
+4. **Decidir**:
+   - Métrica mejora Y Guard pasa → **keep**: commit `experiment(autoresearch): [descripción]`.
+   - Métrica no mejora O Guard falla → **revert**: descartar los cambios del
+     working tree (`git checkout -- [archivos tocados]`). NUNCA reescribir
+     historia para revertir — solo se commitea lo que se conserva.
+   - Verify truena → estado `crash`: descartar cambios, registrar, continuar.
+5. **Registrar** la iteración con `registrarIteracion` (métrica, delta, estado, descripción).
+6. **Condiciones de salida**: target alcanzado → ÉXITO; `detectarPlateau`
+   sobre las últimas 3 filas → PLATEAU (parar, no quemar rounds sin mejora);
+   3 reverts consecutivos → ESTANCAMIENTO (preguntar al usuario);
+   max rounds → ACOTADO.
+
+### Paso C3 — Cierre
+
+1. Escribir handoff: `escribirHandoff(dir, {source: 'swl:autoresearch', status: [COMPLETO|PLATEAU|ACOTADO|INTERRUMPIDO], config})`.
+2. Reporte final con trayectoria (`analizarTrayectoria`): rounds, keep/revert,
+   métrica inicial → final, mayor salto, y los commits `experiment(...)` generados.
+3. Ofrecer al usuario squash de los commits experimentales en un commit
+   semántico final (`git-workflow.md § Squash antes de merge`).
+
+### Reglas adicionales del modo `--codigo`
+
+- NUNCA `git push` desde el loop — los commits experimentales son locales.
+- NUNCA tocar archivos fuera del Scope aprobado.
+- NUNCA continuar tras plateau "por si acaso" — el plateau ES la señal de salida.
+- El hook `contexto-iteracion.js` inyecta el estado del loop en sesiones
+  largas; no releer el TSV completo en cada round (las últimas 3 filas bastan).

package/comandos/swl/evaluar-skill.md

@@ -369,7 +369,7 @@ Umbral de promoción:
 |-------|-------------------------|
 | Platino, Oro, Plata | Promover a `habilidades/`, registrar en manifiestos |
 | Bronce | NO promover, devolver a `_userland/` con feedback |
-| Sin badge | NO promover, registrar rechazo en `.planning/evolucion/promociones-rechazadas.jsonl` |
+| Sin badge | NO promover, registrar rechazo en `.planning/evolution/promociones-rechazadas.jsonl` |
 
 Si un skill es rechazado ≥3 veces consecutivas, el agente escala al usuario
 con análisis de qué dimensiones bajan el score. Origen: ADR 0013 sección 3C.

package/comandos/swl/evolucion-estado.md

@@ -31,7 +31,7 @@ PATH="/c/Program Files/nodejs:/c/Program Files (x86)/nodejs:$PATH" echo '{}' | n
 ## Paso 1 — Cargar métricas
 
 ```bash
-cat .planning/evolucion/metricas.json
+cat .planning/evolution/metricas.json
 ```
 
 Si el archivo no existe: ejecutar el regenerado del Paso 0. Si sigue sin
@@ -58,7 +58,7 @@ echo "RATIO=\"$EVOL_FALSE/$TOTAL\""
 
 Estos valores alimentan la sección KERNEL del template.
 
-Si `.planning/evolucion/politica-evolvable.md` no existe, reportar como
+Si `.planning/evolution/politica-evolvable.md` no existe, reportar como
 hallazgo crítico: el kernel SIN política documentada es violación de
 `reglas/gobernanza.md`.
 
@@ -127,7 +127,7 @@ Template de salida:
       ...
 
   KERNEL (gobernanza)
-    Política evolvable .... .planning/evolucion/politica-evolvable.md
+    Política evolvable .... .planning/evolution/politica-evolvable.md
     Último ADR kernel ..... <ADR-NNNN — título — fecha>
     Agentes evolvable=false <n>/<total>
 
@@ -152,7 +152,7 @@ Al final del dashboard, sugerir acciones según las métricas:
   → `npx -y @saulwade/swl-ses@latest bootstrap-instincts` (pobla desde APRENDIZAJES.md)
 
 - Si `nudges.tasaAccion < 0.3` y `nudges.total > 5`:
-  → "Muchos nudges ignorados. Revisa `.planning/evolucion/alertas-persistentes.json`"
+  → "Muchos nudges ignorados. Revisa `.planning/evolution/alertas-persistentes.json`"
 
 - Si `alertasActivas.length > 0`:
   → listar cada alerta con `/swl:evolucionar <target>` o cmd correspondiente
@@ -178,7 +178,7 @@ Al final del dashboard, sugerir acciones según las métricas:
 
 ## Anti-substitution guardrails
 
-- Archivo de métricas: **siempre** `.planning/evolucion/metricas.json` (nunca `.planning/metricas.json`, `evolucion.json`, `estado-evolucion.json`).
+- Archivo de métricas: **siempre** `.planning/evolution/metricas.json` (nunca `.planning/metricas.json`, `evolucion.json`, `estado-evolucion.json`).
 - Hook que regenera: **siempre** `hooks/metricas-evolucion.js` (nunca `metrics.js`, `evolucion-metricas.js`, `evolution-metrics.js`).
 - Para forzar regen: pipe `echo '{}' | node ...`, nunca invocar `require()` directo.
 

package/comandos/swl/evolucionar.md

@@ -23,7 +23,7 @@ SWL tiene **tres canales independientes** de aprendizaje. Son complementarios, n
 ### Cómo se coordinan
 
 - **Evolución + perfil**: el parser de fricción (`auto-evolucion-protocolo` v1.1) cruza el log
-  `.planning/auto-evolucion/agentes.jsonl` con las señales de corrección del usuario
+  `.planning/auto-evolution/agentes.jsonl` con las señales de corrección del usuario
   para priorizar agentes cuyos runs coincidieron con correcciones. Ver tabla
   "Categorías de fricción" en el skill.
 - **Evolución + aprendizajes**: antes de modificar un skill, leer `APRENDIZAJES.md`
@@ -214,7 +214,7 @@ score_after = (evals_pass / evals_total) * 100 × factor_peso
 | `score_after < score_baseline - 5` | **Revertir** — restaurar el archivo anterior + `--record-revert --score=<N>` |
 | `score_baseline - 5 <= score_after < score_baseline` | **Requiere revisión humana** — reportar diferencia; usuario decide si acepta la regresión menor o revierte |
 
-Los 3 casos registran evento en `.planning/evolucion/evoluciones.jsonl` para el
+Los 3 casos registran evento en `.planning/evolution/evoluciones.jsonl` para el
 dashboard `/swl:evolucion-estado`.
 
 ### Regla de oro

package/comandos/swl/inbox.md

@@ -45,7 +45,7 @@ Por cada comando en la cola, decidir:
 | Instrucción de trabajo clara ("arregla el bug X", "ejecuta pruebas") | Procesar como prompt del usuario. Ejecutar la tarea siguiendo el flujo normal SWL. |
 | Slash command (`/swl:salud`, `/swl:metricas`, etc.) | Invocar ese comando directamente. |
 | Pregunta/consulta ("¿cómo va X?", "estado del release") | Responder con la información solicitada. Enviar respuesta al gateway si aplica. |
-| Feedback/corrección ("no uses Y", "prefiero Z") | Escribir a `.planning/evolucion/feedback-queue.jsonl` con tipo correspondiente y marcar como procesado. |
+| Feedback/corrección ("no uses Y", "prefiero Z") | Escribir a `.planning/evolution/feedback-queue.jsonl` con tipo correspondiente y marcar como procesado. |
 | Contenido ambiguo o sospechoso | Marcar como descartado con razón registrada. |
 
 ### Paso 3 — Procesar y marcar

package/comandos/swl/metricas.md

@@ -22,6 +22,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 loops       — Trayectorias de loops iterativos desde .planning/loops/
 /swl:metricas historico   — Abre el dashboard histórico multi-sesión (alias de /swl:dashboard)
 ```
 
@@ -318,6 +319,39 @@ node scripts/derivar-feature-list.js --check
 
 ---
 
+## Subcomando: `loops` — Trayectorias de loops iterativos
+
+Si el usuario invoca `/swl:metricas loops`, leer las corridas registradas por
+`hooks/lib/loop-telemetry.js` en `.planning/loops/`:
+
+```bash
+node -e "
+const fs = require('fs'), path = require('path');
+const lt = require('./hooks/lib/loop-telemetry');
+const base = path.join(process.cwd(), lt.DIR_LOOPS);
+let dirs = [];
+try { dirs = fs.readdirSync(base).map(d => path.join(base, d)).filter(d => fs.statSync(d).isDirectory()); } catch {}
+if (dirs.length === 0) { console.log('(sin corridas de loops registradas)'); process.exit(0); }
+for (const dir of dirs.sort().slice(-10)) {
+  try {
+    const t = lt.analizarTrayectoria(dir);
+    const h = lt.leerHandoff(dir);
+    console.log(path.basename(dir) + ' | iters: ' + t.totalIteraciones +
+      ' | keep/revert: ' + t.keeps + '/' + t.reverts +
+      ' | métrica: ' + t.metricaInicial + ' → ' + t.metricaFinal +
+      ' | plateau: ' + (t.plateau ? 'SÍ' : 'no') +
+      ' | status: ' + (h ? h.status : 'en curso'));
+  } catch (e) { console.log(path.basename(dir) + ' | (ilegible: ' + e.message + ')'); }
+}
+"
+```
+
+Reportar al usuario en tabla: corrida, iteraciones, keep/revert rate, métrica
+inicial → final, plateau y status del handoff. Si alguna corrida activa muestra
+plateau, sugerir cerrarla — seguir iterando sin mejora quema tokens.
+
+---
+
 ## Subcomando: `historico`
 
 Si el usuario invoca `/swl:metricas historico`, redirigir inmediatamente a: