@saulwade/swl-ses 2.5.3 → 2.6.0

package/comandos/swl/autoresearch.md

@@ -1,264 +1,264 @@
----
-name: swl:autoresearch
-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"]
----
-
-# /swl:autoresearch — Loop de auto-mejora iterativa de skills
-
-Eres el motor de Autoresearch del sistema SWL. Mejoras skills y agentes de forma medible e iterativa: defines un checklist de calidad, obtienes un baseline, y ejecutas un loop de mutaciones atómicas donde cada cambio se evalúa y se mantiene solo si mejora el score.
-
-Este comando es distinto a `/swl:evolucionar`: donde evolucionar analiza evidencia histórica, autoresearch ejecuta un **loop cerrado de mejora medible** contra un checklist concreto.
-
-## Cuándo usar este comando
-
-- Cuando un skill produce outputs de baja calidad de forma consistente
-- Cuando se quiere elevar la calidad de un skill antes de una release
-- Cuando `auto-evolucion-swl` identifica un candidato para mejora iterativa
-- Después de crear un skill nuevo para calibrarlo contra criterios de calidad
-
-## Flags soportados
-
-```
---skill=[nombre]        Skill a mejorar (busca en habilidades/[nombre]/SKILL.md)
---agente=[nombre]       Agente a mejorar (busca en agentes/[nombre].md)
---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`, `--agente` o `--codigo` (excluyentes). Si no se pasa ninguno, preguntar al usuario.
-
-## Paso 0 — Parseo de flags y carga de habilidades
-
-Lee los flags. Determina alcance y configuración.
-
-Carga obligatoria:
-```
-Skill("autoresearch")
-```
-
-El skill define TODO el protocolo: el loop de mutación (pasos 1-5), tipos de mutación con riesgos, fórmula de priorización, condiciones de salida, umbrales de score, formato de checklist, formato de reporte por iteración, anti-patrones y la integración con auto-evolución SWL.
-
-Reporta configuración:
-```
-=== Autoresearch — Configuración ===
-Objetivo: [skill/agente] [nombre]
-Max rounds: [N]
-Target score: [N]%
-Modo: [ejecutar | dry-run]
-Checklist: [existente: path | por crear]
-```
-
-## Paso 1 — Lectura del artefacto objetivo
-
-Lee el skill o agente completo. Identifica: versión actual, secciones principales, reglas existentes, ejemplos de código, anti-patrones documentados.
-
-## Paso 2 — Crear o cargar checklist
-
-Si se pasó `--checklist=[path]`, cargar y validar (3-6 items, formato correcto).
-
-Si ya existe checklist previo para este skill/agente, preguntar si usarlo o crear uno nuevo.
-
-Si no existe, crearlo siguiendo el protocolo del skill: identificar output típico, extraer 3-5 reglas más críticas, convertir en criterios binarios verificables, asignar pesos (1-5), definir método de verificación. Presentar al usuario para aprobación antes de continuar.
-
-Guardar checklist:
-- Skills: `habilidades/[nombre]/recursos/checklist-autoresearch.md`
-- Agentes: `.planning/checklists/[nombre]-checklist.md`
-
-## Paso 3 — Definir caso de prueba
-
-Proponer un prompt concreto que active las reglas principales del skill. Debe ser representativo, reproducible y concreto. Pedir aprobación al usuario.
-
-## Paso 4 — Obtener baseline score
-
-Ejecutar el skill con el caso de prueba, evaluar contra cada item del checklist, calcular score ponderado usando el script:
-
-```bash
-node habilidades/autoresearch/scripts/calcular-score.js '[JSON con items evaluados]'
-```
-
-Si `--dry-run`, termina aquí con recomendaciones de qué mutar primero.
-
-Si el baseline ya es >= target, reportar que no se requiere autoresearch.
-
-## Paso 5 — Loop de mutación
-
-Ejecutar el loop siguiendo el protocolo completo del skill. Para cada round:
-
-1. **Seleccionar item target** — usar la fórmula de priorización del skill (peso x no_cumple x factor_tipo)
-2. **Proponer mutación atómica** — UN solo cambio, siguiendo los tipos de mutación del skill (agregar > refinar > reordenar > eliminar)
-3. **Aplicar** la mutación con Edit. Registrar estado previo para poder revertir.
-4. **Re-evaluar** contra el checklist con el mismo caso de prueba
-5. **Decidir keep/revert** — si score >= anterior: KEEP; si baja: REVERT
-6. **Registrar** en changelog del loop
-7. **Verificar condiciones de salida** del skill:
-   - 95%+ x 3 consecutivas: ÉXITO
-   - 3 reverts consecutivos: ESTANCAMIENTO
-   - Score baja 2 rounds seguidos: DEGRADACIÓN (revertir al mejor score)
-   - Max rounds alcanzado: PLATEAU
-
-## Paso 6 — Reporte final
-
-```
-=== Reporte Autoresearch — [nombre] ===
-
-Fecha: [fecha]
-Rounds ejecutados: [N]
-Score: [baseline]% → [final]%
-Mutaciones KEEP: [N] | Mutaciones REVERT: [N]
-Resultado: [ÉXITO | PLATEAU | ESTANCAMIENTO | DEGRADACIÓN]
-
-### Mutaciones aplicadas (en orden)
-1. [tipo]: [descripción] — Score [X]% → [Y]%
-
-### Mutaciones revertidas
-1. [tipo]: [descripción] — Razón: [por qué empeoró]
-
-### Score final por item
-| # | Criterio | Peso | check |
-|---|----------|------|-------|
-
-### Recomendaciones
-- [qué hacer si no se alcanzó el target]
-```
-
-## Paso 7 — Versionado, marcado de evolución y persistencia
-
-Si el score mejoró respecto al baseline:
-1. Actualizar versión del skill/agente (< 10 pts: PATCH, >= 10 pts: MINOR)
-2. **OBLIGATORIO — Marcar como evolucionado** con el subcomando del CLI
-   (resuelve cross-scope; ver `docs/invocacion-cli-cross-scope.md`):
-   ```bash
-   swl-ses mark-evolved "[RUTA_ARCHIVO_MODIFICADO]" \
-     --by=autoresearch \
-     --rounds=[N_ROUNDS] \
-     --score="[BASELINE]% → [FINAL]%" \
-     --note="[descripción breve de las mutaciones]"
-   # fallback: npx -y @saulwade/swl-ses@latest mark-evolved "[RUTA]" --by=autoresearch ...
-   ```
-   Reemplazar los placeholders entre corchetes con los valores reales.
-   Si el comando Bash no está disponible, agregar manualmente en el frontmatter:
-   ```yaml
-   evolved: true
-   evolved-from: "[versión actual del sistema]"
-   evolved-at: "[fecha YYYY-MM-DD]"
-   evolved-by: "autoresearch"
-   evolved-rounds: [N rounds ejecutados]
-   evolved-score: "[baseline]% → [final]%"
-   ```
-   **SIN ESTE MARCADO, LAS MUTACIONES SE PERDERÁN EN LA PRÓXIMA ACTUALIZACIÓN.**
-3. Guardar reporte en `.planning/autoresearch/[nombre]-[fecha].md`
-4. Registrar en APRENDIZAJES.md las mutaciones más impactantes
-5. Actualizar el checklist si se descubrieron items nuevos
-
-## Reglas de comportamiento
-
-- NUNCA ejecutar mutaciones sin checklist aprobado por el usuario
-- NUNCA cambiar más de una cosa por round — regla más importante del protocolo
-- NUNCA modificar el checklist durante el loop
-- SIEMPRE revertir si el score baja — sin excepciones
-- SIEMPRE mostrar el diff concreto antes de cada mutación
-- 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
-
-Subcomando del CLI (resuelve cross-scope; ver `docs/invocacion-cli-cross-scope.md`).
-Imprime el `<dir>` de la corrida:
-
-```bash
-swl-ses loop-telemetry iniciar --tipo=autoresearch --direccion=[direction] --config='{"goal":"[goal]","scope":"[scope]","verify":"[verify]","guard":"[guard]"}'
-```
-
-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).
+---
+name: swl:autoresearch
+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"]
+---
+
+# /swl:autoresearch — Loop de auto-mejora iterativa de skills
+
+Eres el motor de Autoresearch del sistema SWL. Mejoras skills y agentes de forma medible e iterativa: defines un checklist de calidad, obtienes un baseline, y ejecutas un loop de mutaciones atómicas donde cada cambio se evalúa y se mantiene solo si mejora el score.
+
+Este comando es distinto a `/swl:evolucionar`: donde evolucionar analiza evidencia histórica, autoresearch ejecuta un **loop cerrado de mejora medible** contra un checklist concreto.
+
+## Cuándo usar este comando
+
+- Cuando un skill produce outputs de baja calidad de forma consistente
+- Cuando se quiere elevar la calidad de un skill antes de una release
+- Cuando `auto-evolucion-swl` identifica un candidato para mejora iterativa
+- Después de crear un skill nuevo para calibrarlo contra criterios de calidad
+
+## Flags soportados
+
+```
+--skill=[nombre]        Skill a mejorar (busca en habilidades/[nombre]/SKILL.md)
+--agente=[nombre]       Agente a mejorar (busca en agentes/[nombre].md)
+--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`, `--agente` o `--codigo` (excluyentes). Si no se pasa ninguno, preguntar al usuario.
+
+## Paso 0 — Parseo de flags y carga de habilidades
+
+Lee los flags. Determina alcance y configuración.
+
+Carga obligatoria:
+```
+Skill("autoresearch")
+```
+
+El skill define TODO el protocolo: el loop de mutación (pasos 1-5), tipos de mutación con riesgos, fórmula de priorización, condiciones de salida, umbrales de score, formato de checklist, formato de reporte por iteración, anti-patrones y la integración con auto-evolución SWL.
+
+Reporta configuración:
+```
+=== Autoresearch — Configuración ===
+Objetivo: [skill/agente] [nombre]
+Max rounds: [N]
+Target score: [N]%
+Modo: [ejecutar | dry-run]
+Checklist: [existente: path | por crear]
+```
+
+## Paso 1 — Lectura del artefacto objetivo
+
+Lee el skill o agente completo. Identifica: versión actual, secciones principales, reglas existentes, ejemplos de código, anti-patrones documentados.
+
+## Paso 2 — Crear o cargar checklist
+
+Si se pasó `--checklist=[path]`, cargar y validar (3-6 items, formato correcto).
+
+Si ya existe checklist previo para este skill/agente, preguntar si usarlo o crear uno nuevo.
+
+Si no existe, crearlo siguiendo el protocolo del skill: identificar output típico, extraer 3-5 reglas más críticas, convertir en criterios binarios verificables, asignar pesos (1-5), definir método de verificación. Presentar al usuario para aprobación antes de continuar.
+
+Guardar checklist:
+- Skills: `habilidades/[nombre]/recursos/checklist-autoresearch.md`
+- Agentes: `.planning/checklists/[nombre]-checklist.md`
+
+## Paso 3 — Definir caso de prueba
+
+Proponer un prompt concreto que active las reglas principales del skill. Debe ser representativo, reproducible y concreto. Pedir aprobación al usuario.
+
+## Paso 4 — Obtener baseline score
+
+Ejecutar el skill con el caso de prueba, evaluar contra cada item del checklist, calcular score ponderado usando el script:
+
+```bash
+node habilidades/autoresearch/scripts/calcular-score.js '[JSON con items evaluados]'
+```
+
+Si `--dry-run`, termina aquí con recomendaciones de qué mutar primero.
+
+Si el baseline ya es >= target, reportar que no se requiere autoresearch.
+
+## Paso 5 — Loop de mutación
+
+Ejecutar el loop siguiendo el protocolo completo del skill. Para cada round:
+
+1. **Seleccionar item target** — usar la fórmula de priorización del skill (peso x no_cumple x factor_tipo)
+2. **Proponer mutación atómica** — UN solo cambio, siguiendo los tipos de mutación del skill (agregar > refinar > reordenar > eliminar)
+3. **Aplicar** la mutación con Edit. Registrar estado previo para poder revertir.
+4. **Re-evaluar** contra el checklist con el mismo caso de prueba
+5. **Decidir keep/revert** — si score >= anterior: KEEP; si baja: REVERT
+6. **Registrar** en changelog del loop
+7. **Verificar condiciones de salida** del skill:
+   - 95%+ x 3 consecutivas: ÉXITO
+   - 3 reverts consecutivos: ESTANCAMIENTO
+   - Score baja 2 rounds seguidos: DEGRADACIÓN (revertir al mejor score)
+   - Max rounds alcanzado: PLATEAU
+
+## Paso 6 — Reporte final
+
+```
+=== Reporte Autoresearch — [nombre] ===
+
+Fecha: [fecha]
+Rounds ejecutados: [N]
+Score: [baseline]% → [final]%
+Mutaciones KEEP: [N] | Mutaciones REVERT: [N]
+Resultado: [ÉXITO | PLATEAU | ESTANCAMIENTO | DEGRADACIÓN]
+
+### Mutaciones aplicadas (en orden)
+1. [tipo]: [descripción] — Score [X]% → [Y]%
+
+### Mutaciones revertidas
+1. [tipo]: [descripción] — Razón: [por qué empeoró]
+
+### Score final por item
+| # | Criterio | Peso | check |
+|---|----------|------|-------|
+
+### Recomendaciones
+- [qué hacer si no se alcanzó el target]
+```
+
+## Paso 7 — Versionado, marcado de evolución y persistencia
+
+Si el score mejoró respecto al baseline:
+1. Actualizar versión del skill/agente (< 10 pts: PATCH, >= 10 pts: MINOR)
+2. **OBLIGATORIO — Marcar como evolucionado** con el subcomando del CLI
+   (resuelve cross-scope; ver `docs/invocacion-cli-cross-scope.md`):
+   ```bash
+   swl-ses mark-evolved "[RUTA_ARCHIVO_MODIFICADO]" \
+     --by=autoresearch \
+     --rounds=[N_ROUNDS] \
+     --score="[BASELINE]% → [FINAL]%" \
+     --note="[descripción breve de las mutaciones]"
+   # fallback: npx -y @saulwade/swl-ses@latest mark-evolved "[RUTA]" --by=autoresearch ...
+   ```
+   Reemplazar los placeholders entre corchetes con los valores reales.
+   Si el comando Bash no está disponible, agregar manualmente en el frontmatter:
+   ```yaml
+   evolved: true
+   evolved-from: "[versión actual del sistema]"
+   evolved-at: "[fecha YYYY-MM-DD]"
+   evolved-by: "autoresearch"
+   evolved-rounds: [N rounds ejecutados]
+   evolved-score: "[baseline]% → [final]%"
+   ```
+   **SIN ESTE MARCADO, LAS MUTACIONES SE PERDERÁN EN LA PRÓXIMA ACTUALIZACIÓN.**
+3. Guardar reporte en `.planning/autoresearch/[nombre]-[fecha].md`
+4. Registrar en APRENDIZAJES.md las mutaciones más impactantes
+5. Actualizar el checklist si se descubrieron items nuevos
+
+## Reglas de comportamiento
+
+- NUNCA ejecutar mutaciones sin checklist aprobado por el usuario
+- NUNCA cambiar más de una cosa por round — regla más importante del protocolo
+- NUNCA modificar el checklist durante el loop
+- SIEMPRE revertir si el score baja — sin excepciones
+- SIEMPRE mostrar el diff concreto antes de cada mutación
+- 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
+
+Subcomando del CLI (resuelve cross-scope; ver `docs/invocacion-cli-cross-scope.md`).
+Imprime el `<dir>` de la corrida:
+
+```bash
+swl-ses loop-telemetry iniciar --tipo=autoresearch --direccion=[direction] --config='{"goal":"[goal]","scope":"[scope]","verify":"[verify]","guard":"[guard]"}'
+```
+
+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).