@saulwade/swl-ses 2.1.0 → 2.2.0

package/comandos/swl/aprobar-plan.md

@@ -15,6 +15,14 @@ a mano (`estado: aprobado`) deja el plan en modo legacy (cláusula de gracia D-0
 se ejecuta con advertencia pero sin protección de integridad. Usar este comando
 es lo que activa el gate real.
 
+> **Invocación cross-scope** (ver `@docs/invocacion-cli-cross-scope.md`): las
+> partes deterministas del gate viven en subcomandos del CLI. Resuélvelos así:
+> si existe `./scripts/cli/<sub>.js` (repo madre) usa `node scripts/cli/<sub>.js`;
+> si `command -v swl-ses` responde usa `swl-ses <sub>`; si no,
+> `npx -y @saulwade/swl-ses@latest <sub>`. Abajo escribo la forma `swl-ses <sub>`
+> como canónica. NUNCA uses `node -e "require('./scripts/lib/...')"` — esa ruta no
+> existe en proyectos downstream.
+
 ## Uso
 
 ```
@@ -37,7 +45,7 @@ Lee el campo `estado:` del frontmatter:
 - Si `estado: borrador` → continúa al Paso 3 (caso normal).
 - Si `estado: aprobado` → ya está aprobado. Verifica si existe el lock:
   ```bash
-  node -e "const {verificarPlan}=require('./scripts/lib/plan-lock'); console.log(JSON.stringify(verificarPlan('.planning/fases/0N-PLAN.md')))"
+  swl-ses verificar-plan --fase=N
   ```
   - Si `modo: "firmado"` → informa "El plan ya está aprobado y firmado." y termina.
   - Si `modo: "legacy"` (aprobado sin lock) → pregunta al usuario: "El plan está
@@ -59,7 +67,7 @@ aceptación. `verificar-trazabilidad.js` reconoce ambos formatos.
   ("CONTEXTO sin REQ-IDs — trazabilidad no exigible, gracia legacy") y continúa.
 - **CONTEXTO con REQ-IDs**: verifica que el PLAN cubra TODOS:
   ```bash
-  node scripts/verificar-trazabilidad.js --fase=N --solo-plan
+  swl-ses verificar-trazabilidad --fase=N --solo-plan
   ```
   - Exit 0 → continúa al Paso 3.
   - Exit 1 (REQ huérfanos) → **RECHAZA la aprobación**. Lista los REQ sin tarea y
@@ -86,41 +94,21 @@ a `/swl:planear-fase N` para refinar.
    edita el frontmatter `estado: borrador` → `estado: aprobado` y agrega
    `aprobadoPor: usuario (<nombre>) — <fecha>, via /swl:aprobar-plan`.
 
-2. **Firmar** — escribe el lock SHA256:
-   ```bash
-   node -e "const {firmarPlan}=require('./scripts/lib/plan-lock'); const r=firmarPlan('.planning/fases/0N-PLAN.md'); console.log(JSON.stringify(r))"
-   ```
-   Verifica que el resultado sea `ok: true` y que exista
-   `.planning/locks/0N-PLAN.md.lock`.
-
-3. **Verificar** la firma de inmediato:
-   ```bash
-   node -e "const {verificarPlan}=require('./scripts/lib/plan-lock'); console.log(JSON.stringify(verificarPlan('.planning/fases/0N-PLAN.md')))"
-   ```
-   Debe retornar `modo: "firmado"`, `ok: true`.
-
-4. **Marcar la fase como activa** (gate G0 — `hooks/spec-gate.js` consume este
-   archivo): escribe `.planning/locks/fase-activa.json` con el sha256 devuelto
-   por `firmarPlan`:
+2. **Firmar y marcar la fase activa** — un solo subcomando hace las tres
+   operaciones deterministas: firma SHA256 → `.planning/locks/0N-PLAN.md.lock`,
+   verifica la firma, y escribe `.planning/locks/fase-activa.json` (gate G0 que
+   consume `hooks/spec-gate.js`):
    ```bash
-   node -e "
-   const {atomicWriteJSON} = require('./hooks/lib/atomic-write');
-   const {verificarPlan} = require('./scripts/lib/plan-lock');
-   const v = verificarPlan('.planning/fases/0N-PLAN.md');
-   atomicWriteJSON('.planning/locks/fase-activa.json', {
-     numero: N,
-     planPath: '.planning/fases/0N-PLAN.md',
-     sha256: v.hashEsperado,
-     aprobadoEn: new Date().toISOString(),
-     aprobadoPor: 'usuario via /swl:aprobar-plan'
-   });
-   console.log('fase activa: 0N');
-   "
+   swl-ses aprobar-plan --fase=N
    ```
-   Este archivo es runtime local (gitignored — a diferencia del `.lock`, que SÍ
-   se versiona como evidencia). `/swl:ejecutar-fase` lo elimina al cerrar la fase.
-   Si se re-firma un plan (re-aprobación tras mutación), re-escribir también
-   fase-activa.json para que el hash quede alineado.
+   Verifica en la salida JSON que `ok: true` y `modo: "firmado"`. Si reporta
+   error de firma, **NO continúes** — revisa el `motivo`.
+
+   El `.lock` SÍ se versiona en git (evidencia de aprobación, parte del audit
+   trail SDD). El `fase-activa.json` es runtime local (gitignored);
+   `/swl:ejecutar-fase` lo elimina al cerrar la fase. Re-ejecutar
+   `swl-ses aprobar-plan --fase=N` tras una re-aprobación (plan mutado) realinea
+   lock y fase-activa automáticamente.
 
 ## Paso 5 — Reporte
 

package/comandos/swl/autoresearch.md

@@ -135,20 +135,15 @@ Resultado: [ÉXITO | PLATEAU | ESTANCAMIENTO | DEGRADACIÓN]
 
 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 ejecutando este comando Bash**:
+2. **OBLIGATORIO — Marcar como evolucionado** con el subcomando del CLI
+   (resuelve cross-scope; ver `docs/invocacion-cli-cross-scope.md`):
    ```bash
-   node -e "
-   const { markAsEvolved } = require('./hooks/lib/evolution-tracker');
-   const pkg = require('./package.json');
-   const r = markAsEvolved('[RUTA_ARCHIVO_MODIFICADO]', {
-     from: pkg.version,
-     by: 'autoresearch',
-     rounds: [N_ROUNDS],
-     score: '[BASELINE]% → [FINAL]%',
-     note: '[descripción breve de las mutaciones]'
-   });
-   console.log(r.marked ? 'Marcado como evolucionado' : 'Error: ' + r.error);
-   "
+   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:
@@ -220,8 +215,11 @@ 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
-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)"
+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:

package/comandos/swl/briefing.md

@@ -28,12 +28,9 @@ Ejecuta los recolectores de filesystem y presenta el digest sin tope de 5 (aquí
 sí caben todas, no hay presupuesto de latencia de arranque):
 
 ```bash
-node -e "
-const b = require('./hooks/lib/briefing.js');
-const items = b.recolectarTodo(process.cwd(), new Date());
-for (const it of items) console.log('— [' + it.categoria + '] ' + it.titulo + ' → ' + it.accion);
-if (items.length === 0) console.log('(sin señales baratas)');
-"
+# Subcomando del CLI (resuelve cross-scope; ver docs/invocacion-cli-cross-scope.md)
+swl-ses briefing
+# fallback: npx -y @saulwade/swl-ses@latest briefing
 ```
 
 Las 5 categorías: `adr-vencido`, `deuda-trigger`, `nudges-pendientes`,
@@ -78,11 +75,11 @@ commits sin revisión asociada. Si no está disponible → omitir con nota.
 ### 2.4 — Drift de feature-list
 
 ```bash
-node scripts/derivar-feature-list.js --check 2>/dev/null; echo "exit: $?"
+swl-ses derivar-feature-list --check 2>/dev/null; echo "exit: $?"
 ```
 
 Exit 2 → reportar que `HOJA-RUTA.md` y `feature-list.json` divergieron, con la
-acción `node scripts/derivar-feature-list.js` para regenerar.
+acción `swl-ses derivar-feature-list` para regenerar.
 
 ### 2.5 — Deuda con trigger en prosa libre
 

package/comandos/swl/checkpoint.md

@@ -221,24 +221,19 @@ cat .planning/execution-state.json 2>/dev/null || echo "(sin estado de ejecució
 ```
 
 Si existe, actualizar el campo `proximoAgente` con la siguiente tarea pendiente.
-Si no existe y hay un plan en progreso con agentes ejecutados en esta sesión, crear el estado:
+Si no existe y hay un plan en progreso con agentes ejecutados en esta sesión,
+imprimir el resumen estructurado con el subcomando del CLI (resuelve cross-scope;
+ver `docs/invocacion-cli-cross-scope.md`):
 
-```javascript
-// Ejemplo de actualización manual desde el orquestador o skill ejecutar-fase:
-const es = require('./hooks/lib/execution-state');
-
-// Registrar agentes completados en esta sesión
-// es.completarAgente(cwd, 'nombre-agente', 'slice', { resumen: '...' });
-
-// Registrar el próximo agente a ejecutar
-// es.establecerProximo(cwd, 'proximo-agente', 'proximo-slice');
-
-// Ver resumen del estado
-console.log(es.formatearResumen(process.cwd()));
+```bash
+swl-ses execution-state
+# fallback: npx -y @saulwade/swl-ses@latest execution-state
 ```
 
-Incluir el resumen de `formatearResumen()` en el `continue-here.md` generado en el Paso 4,
-bajo la sección "Qué se estaba haciendo".
+Incluir ese resumen en el `continue-here.md` generado en el Paso 4, bajo la
+sección "Qué se estaba haciendo". El registro de agentes
+(`completarAgente`/`establecerProximo`) lo gestiona el skill `ejecutar-fase`
+internamente; aquí solo se lee el resumen.
 
 ## Paso 4 — Creación del continue-here.md