@saulwade/swl-ses 2.0.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á
@@ -51,14 +59,15 @@ Lee el campo `estado:` del frontmatter:
 
 ## Paso 2.5 — Validar la matriz REQ×T (trazabilidad G4)
 
-Lee `.planning/fases/0N-CONTEXTO.md` y extrae los IDs `REQ-NN:` de la sección de
-criterios de aceptación.
+Lee `.planning/fases/0N-CONTEXTO.md` y extrae los IDs `REQ-NN:` (fases 01-11) o
+`REQ-<fase>-NN:` (namespaceados, fases ≥12) de la sección de criterios de
+aceptación. `verificar-trazabilidad.js` reconoce ambos formatos.
 
 - **CONTEXTO sin REQ-IDs** (fases legacy 01-09): advertencia informativa
   ("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
@@ -85,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

@@ -0,0 +1,119 @@
+---
+name: swl:briefing
+description: Briefing proactivo del proyecto bajo demanda. Re-presenta las señales baratas del hook SessionStart (ADRs Propuestos con reevaluación vencida, deuda con trigger por fecha cumplido, nudges sin accionar, gates en calibración, retoma pendiente) y agrega el análisis profundo opt-in que el hook no puede pagar: audit de dependencias del proyecto destino, cobertura vs umbral, hubs del grafo tocados sin revisión, drift de feature-list, y triggers de deuda en prosa libre. Cargar cuando el usuario pide "¿qué hay pendiente?", "¿qué riesgos hay?", "ponme al día", o cuando el digest de sesión sugiere el análisis completo por volumen de señales.
+allowed_tools: ["Read", "Bash", "Glob", "Grep"]
+---
+
+# /swl:briefing — Briefing proactivo bajo demanda
+
+Análisis no solicitado del estado del proyecto destino (Fase 12, ADR-0036). El
+hook `session-briefing.js` da el digest barato al abrir sesión; este comando es
+el nivel profundo: re-presenta esas señales Y agrega las que cuestan (deps, grafo,
+cobertura) con degradación funcional si la herramienta no está instalada.
+
+Principio rector: **proponer es barato y siempre permitido; actuar requiere
+autorización del usuario**. Este comando solo propone y analiza — nunca aplica
+cambios sin que el usuario los pida.
+
+## Uso
+
+```
+/swl:briefing            # señales baratas + análisis profundo completo
+/swl:briefing rapido     # solo las 5 señales del hook (sin deps/grafo/cobertura)
+```
+
+## Paso 1 — Señales baratas (mismas del hook)
+
+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
+# 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`,
+`gate-calibracion`, `continue-here`. Si `rapido`, terminar aquí.
+
+## Paso 2 — Análisis profundo (opt-in, con degradación)
+
+Para cada herramienta, **validar antes de invocar** (patrón "validar antes de
+invocar"): si no está disponible, reportar "no disponible, omitido" y continuar —
+nunca fallar el briefing por una herramienta ausente.
+
+### 2.1 — Audit de dependencias del proyecto destino
+
+Detectar el ecosistema y correr el audit nativo:
+
+```bash
+# Node
+[ -f package.json ] && npm audit --omit=dev 2>/dev/null | tail -5
+# Python
+[ -f requirements.txt -o -f pyproject.toml ] && (command -v pip-audit >/dev/null && pip-audit 2>/dev/null | tail -5 || echo "pip-audit no instalado — omitido")
+```
+
+Reportar CVEs HIGH/CRITICAL con la acción concreta (`npm audit fix`, bump de
+versión). Sin lockfile o sin gestor → omitir.
+
+### 2.2 — Cobertura vs umbral
+
+Si el proyecto define cobertura, comparar contra el umbral del proyecto (80% por
+defecto). Si no hay reporte reciente, indicar el comando para generarlo en vez de
+correrlo (puede ser caro):
+
+```
+Para medir cobertura: <runner del proyecto> --coverage
+```
+
+### 2.3 — Hubs del grafo tocados sin revisión
+
+Si el MCP `code-review-graph` está disponible (tools `mcp__code-review-graph__*`
+registradas o deferred), consultar los nodos hub modificados en los últimos N
+commits sin revisión asociada. Si no está disponible → omitir con nota.
+
+### 2.4 — Drift de feature-list
+
+```bash
+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 `swl-ses derivar-feature-list` para regenerar.
+
+### 2.5 — Deuda con trigger en prosa libre
+
+El hook solo evalúa triggers verificables por fecha (D-16). Aquí, leer
+`.planning/DEUDA-TECNICA.md` y evaluar con criterio los triggers en prosa
+("≥2 clientes reportan", "p95 > 60s documentado") contra el estado real del
+proyecto. Reportar los que parezcan cumplidos para revisión del usuario.
+
+## Paso 3 — Presentación y telemetría
+
+Presenta el briefing agrupado por prioridad (continue-here → gates → deuda →
+ADRs → nudges → hallazgos profundos). Cada ítem con su acción ejecutable.
+
+Tras presentar, el usuario decide qué accionar. NO ejecutar acciones de mutación
+(cerrar deuda, promover gates, aplicar fixes) sin que el usuario lo pida — este
+comando es propositivo (separación PROPONER/ACTUAR, ADR-0037 pendiente).
+
+Si el usuario acciona una señal en esta sesión (ejecuta el comando sugerido), esa
+resolución la captura la telemetría de aceptación del hook en la siguiente sesión
+(la señal desaparece del recolector → cuenta como "actuada", D-18).
+
+## Cuándo NO usar este comando
+
+- En cada turno de una sesión: el briefing es por sesión, no por mensaje. El hook
+  ya cubre el inicio; este comando es para cuando el usuario pide el detalle.
+- Para aplicar las acciones propuestas: este comando propone, no ejecuta. Usar el
+  comando concreto de cada señal (`/swl:evolucion-estado`, `/swl:verificar`, etc.).
+- En proyectos sin `.planning/`: no hay señales que recolectar.
+
+## Gotchas
+
+- **Herramienta ausente ≠ error**: si `npm audit`, `pip-audit` o el grafo no están,
+  el briefing los omite con nota y sigue. Nunca abortar por una dependencia opt-in.
+- **No re-listar lo que el hook ya mostró hoy**: el hook aplica dedupe diario; este
+  comando ignora el dedupe a propósito (lo invoca el usuario, quiere ver todo).
+- **`code-review-graph` deferred ≠ ausente**: si las tools aparecen como deferred,
+  cargar su schema con `ToolSearch` antes de concluir que no está disponible.

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