@saulwade/swl-ses 2.2.4 → 2.3.0

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md — @saulwade/swl-ses v2.2.4
+# CLAUDE.md — @saulwade/swl-ses v2.3.0
 
 ## Reglas de máxima prioridad (aplican SIEMPRE, sin excepción)
 
@@ -99,7 +99,7 @@ NUNCA asumir, sugerir como hecho consumado, ni escribir en ADRs/manifiestos/CHAN
 ## Qué es este repositorio
 
 Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot (SDLC completo).
-11 lenguajes, 7 runtimes (Claude, OpenClaude, OpenCode, Gemini, Cursor, Codex, Copilot), 60 agentes, 182 skills, 44 comandos, 77 reglas, 48 hooks.
+11 lenguajes, 7 runtimes (Claude, OpenClaude, OpenCode, Gemini, Cursor, Codex, Copilot), 60 agentes, 182 skills, 44 comandos, 77 reglas, 50 hooks.
 
 ## Estructura del repositorio
 

package/README.md

@@ -1,4 +1,4 @@
-# swl-ses v2.2.4
+# swl-ses v2.3.0
 
 > El paquete anterior `@saulwadeleon/swl-software-engineering-system` está deprecado. Migrar a `@saulwade/swl-ses` (npmjs.org canónico) o `@saul-wade/swl-ses` (mirror en GitHub Packages) — el CLI `swl-ses` no cambia.
 
@@ -213,7 +213,7 @@ Correr solo uno deja el otro plano en una versión anterior.
 | `mobile` | Android + iOS + React Native/Flutter + UX |
 | `devops` | CI/CD + cloud + observabilidad + releases + seguridad |
 | `polyglot` | Todos los lenguajes: 11 lenguajes + revisores + build resolvers |
-| `completo` | Todo: 60 agentes + 182 habilidades + 44 comandos + 77 reglas + 48 hooks |
+| `completo` | Todo: 60 agentes + 182 habilidades + 44 comandos + 77 reglas + 50 hooks |
 
 ### Targets soportados
 
@@ -518,7 +518,7 @@ swl-ses/
   habilidades/              # 160 habilidades modulares
   comandos/swl/             # 44 comandos slash
   reglas/                   # 28 reglas base + 40 por lenguaje
-  hooks/                    # 48 hooks + 76 librerías en hooks/lib/
+  hooks/                    # 50 hooks + 77 librerías en hooks/lib/
   schemas/                  # 15 JSON Schemas
   contextos/                # 3 modos de desarrollo
   instintos/                # Instintos YAML con confianza

package/comandos/swl/aprobar-plan.md

@@ -1,141 +1,146 @@
----
-name: swl:aprobar-plan
-description: Aprueba el PLAN.md de una fase y lo firma con un lock SHA256 (gate G1 de SDD). Transiciona el frontmatter de estado borrador a aprobado y escribe .planning/locks/<plan>.lock. Es la única vía válida de aprobación — ejecutar-fase verifica este lock antes de implementar y detiene la ejecución si el plan fue mutado tras la firma.
-allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob"]
----
-
-# /swl:aprobar-plan <n> — Aprobar y firmar el plan de una fase (Gate G1)
-
-Eres el guardián del gate G1 del enforcement SDD. Tu trabajo es transicionar un
-PLAN de `borrador` a `aprobado` Y firmarlo con un lock SHA256, de modo que
-cualquier mutación posterior del plan sea detectable por `/swl:ejecutar-fase`.
-
-Este comando es la **única vía documentada de aprobación**. Editar el frontmatter
-a mano (`estado: aprobado`) deja el plan en modo legacy (cláusula de gracia D-05):
-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
-
-```
-/swl:aprobar-plan 9
-```
-
-El argumento `<n>` es el número de la fase cuyo PLAN se aprueba.
-
-## Paso 1 — Localizar el PLAN
-
-Resuelve la ruta `.planning/fases/0N-PLAN.md` (N con cero a la izquierda si N < 10).
-
-- Si no existe: detente con "No existe el PLAN de la fase N. Ejecuta `/swl:planear-fase N` primero."
-- Lee el archivo completo.
-
-## Paso 2 — Validar el estado actual del frontmatter
-
-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
-  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á
-    aprobado pero sin firmar (modo legacy). ¿Lo firmo ahora para activar el gate
-    G1?" Si confirma, salta al Paso 4 (firmar sin re-transicionar).
-  - Si `modo: "mutado"` → el plan cambió tras una firma previa. Informa el
-    `hashEsperado` vs `hashActual` y pregunta si re-aprobar (re-firmar el estado
-    actual). Procede solo con confirmación explícita.
-- Si no hay campo `estado` → detente: "El PLAN no tiene campo `estado` en el
-  frontmatter. Revisa que sea un plan válido generado por `/swl:planear-fase`."
-
-## Paso 2.5 — Validar la matriz REQ×T (trazabilidad G4)
-
-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
-  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
-    remite a `/swl:planear-fase N` para cubrirlos (o a retirar el REQ del CONTEXTO
-    con marca "RETIRADO — razón"). NO firmes un plan con REQ huérfanos.
-
-## Paso 3 — Confirmar con el usuario antes de aprobar
-
-NUNCA apruebes sin confirmación explícita. Presenta un resumen breve del plan
-(número de slices, tareas, slices HITL) y pregunta:
-
-```
-El plan de la fase N tiene [X] slices y [Y] tareas ([Z] HITL).
-¿Confirmas la aprobación? Al aprobar se firma con SHA256 y queda inmutable:
-cualquier edición posterior detendrá /swl:ejecutar-fase.
-```
-
-Espera respuesta afirmativa. Si el usuario pide cambios, NO apruebes — remítelo
-a `/swl:planear-fase N` para refinar.
-
-## Paso 4 — Transicionar y firmar
-
-1. **Transicionar** (omitir si el plan ya estaba `aprobado` en modo legacy):
-   edita el frontmatter `estado: borrador` → `estado: aprobado` y agrega
-   `aprobadoPor: usuario (<nombre>) — <fecha>, via /swl:aprobar-plan`.
-
-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
-   swl-ses aprobar-plan --fase=N
-   ```
-   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
-
-```
-Plan de la fase N aprobado y firmado (gate G1 activo).
-
-estado: borrador -> aprobado
-lock: .planning/locks/0N-PLAN.md.lock
-fase activa: .planning/locks/fase-activa.json (gate G0 cubierto)
-sha256: <hash corto>
-
-Cualquier edición del PLAN tras esta firma detendrá /swl:ejecutar-fase con un
-mensaje de "plan mutado tras aprobación". Para cambiar el plan: edítalo y vuelve
-a ejecutar /swl:aprobar-plan N.
-
-Próximo paso: /swl:ejecutar-fase N
-```
-
-## Reglas de comportamiento
-
-- NUNCA apruebes un plan sin confirmación explícita del usuario.
-- NUNCA modifiques el contenido del plan al aprobarlo — solo el campo `estado`
-  del frontmatter y la línea `aprobadoPor`. El cuerpo es lo que se firma.
-- El lock vive en `.planning/locks/` y SÍ se versiona en git (es evidencia de
-  aprobación, parte del audit trail de SDD).
-- Si el usuario quiere cambiar el plan después de aprobado, el flujo correcto es
-  editar el PLAN y re-ejecutar `/swl:aprobar-plan N` (re-firma). NUNCA editar el
-  lock a mano.
-- El número de versión del release que publique esta fase lo decide el usuario
-  (regla CLAUDE.md) — este comando no toca versiones.
+---
+name: swl:aprobar-plan
+description: Aprueba el PLAN.md de una fase y lo firma con un lock SHA256 (gate G1 de SDD). Transiciona el frontmatter de estado borrador a aprobado y escribe .planning/locks/<plan>.lock. Es la única vía válida de aprobación — ejecutar-fase verifica este lock antes de implementar y detiene la ejecución si el plan fue mutado tras la firma.
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob"]
+---
+
+# /swl:aprobar-plan <n> — Aprobar y firmar el plan de una fase (Gate G1)
+
+Eres el guardián del gate G1 del enforcement SDD. Tu trabajo es transicionar un
+PLAN de `borrador` a `aprobado` Y firmarlo con un lock SHA256, de modo que
+cualquier mutación posterior del plan sea detectable por `/swl:ejecutar-fase`.
+
+Este comando es la **única vía documentada de aprobación**. Editar el frontmatter
+a mano (`estado: aprobado`) deja el plan en modo legacy (cláusula de gracia D-05):
+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
+
+```
+/swl:aprobar-plan 9
+```
+
+El argumento `<n>` es el número de la fase cuyo PLAN se aprueba.
+
+## Paso 1 — Localizar el PLAN
+
+Resuelve la ruta `.planning/fases/0N-PLAN.md` (N con cero a la izquierda si N < 10).
+
+- Si no existe: detente con "No existe el PLAN de la fase N. Ejecuta `/swl:planear-fase N` primero."
+- Lee el archivo completo.
+
+## Paso 2 — Validar el estado actual del frontmatter
+
+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
+  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á
+    aprobado pero sin firmar (modo legacy). ¿Lo firmo ahora para activar el gate
+    G1?" Si confirma, salta al Paso 4 (firmar sin re-transicionar).
+  - Si `modo: "mutado"` → el plan cambió tras una firma previa. Informa el
+    `hashEsperado` vs `hashActual` y pregunta si re-aprobar (re-firmar el estado
+    actual). Procede solo con confirmación explícita.
+- Si no hay campo `estado` → detente: "El PLAN no tiene campo `estado` en el
+  frontmatter. Revisa que sea un plan válido generado por `/swl:planear-fase`."
+
+## Paso 2.5 — Validar la matriz REQ×T (trazabilidad G4)
+
+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
+  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
+    remite a `/swl:planear-fase N` para cubrirlos (o a retirar el REQ del CONTEXTO
+    con marca "RETIRADO — razón"). NO firmes un plan con REQ huérfanos.
+  - **WARN "headers de tarea malformados"** (warn-only, no cambia el exit): si el
+    reporte lista headers como `#### T-01 — ...`, son la **causa silenciosa** de
+    REQ huérfanos. El parser de la matriz exige `### T-NN:` (2-4 `#`, dos puntos
+    tras el ID; nunca em-dash). Corrige el separador en el PLAN y re-ejecuta antes
+    de aprobar — un header con `—` deja la tarea invisible aunque declare su REQ.
+
+## Paso 3 — Confirmar con el usuario antes de aprobar
+
+NUNCA apruebes sin confirmación explícita. Presenta un resumen breve del plan
+(número de slices, tareas, slices HITL) y pregunta:
+
+```
+El plan de la fase N tiene [X] slices y [Y] tareas ([Z] HITL).
+¿Confirmas la aprobación? Al aprobar se firma con SHA256 y queda inmutable:
+cualquier edición posterior detendrá /swl:ejecutar-fase.
+```
+
+Espera respuesta afirmativa. Si el usuario pide cambios, NO apruebes — remítelo
+a `/swl:planear-fase N` para refinar.
+
+## Paso 4 — Transicionar y firmar
+
+1. **Transicionar** (omitir si el plan ya estaba `aprobado` en modo legacy):
+   edita el frontmatter `estado: borrador` → `estado: aprobado` y agrega
+   `aprobadoPor: usuario (<nombre>) — <fecha>, via /swl:aprobar-plan`.
+
+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
+   swl-ses aprobar-plan --fase=N
+   ```
+   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
+
+```
+Plan de la fase N aprobado y firmado (gate G1 activo).
+
+estado: borrador -> aprobado
+lock: .planning/locks/0N-PLAN.md.lock
+fase activa: .planning/locks/fase-activa.json (gate G0 cubierto)
+sha256: <hash corto>
+
+Cualquier edición del PLAN tras esta firma detendrá /swl:ejecutar-fase con un
+mensaje de "plan mutado tras aprobación". Para cambiar el plan: edítalo y vuelve
+a ejecutar /swl:aprobar-plan N.
+
+Próximo paso: /swl:ejecutar-fase N
+```
+
+## Reglas de comportamiento
+
+- NUNCA apruebes un plan sin confirmación explícita del usuario.
+- NUNCA modifiques el contenido del plan al aprobarlo — solo el campo `estado`
+  del frontmatter y la línea `aprobadoPor`. El cuerpo es lo que se firma.
+- El lock vive en `.planning/locks/` y SÍ se versiona en git (es evidencia de
+  aprobación, parte del audit trail de SDD).
+- Si el usuario quiere cambiar el plan después de aprobado, el flujo correcto es
+  editar el PLAN y re-ejecutar `/swl:aprobar-plan N` (re-firma). NUNCA editar el
+  lock a mano.
+- El número de versión del release que publique esta fase lo decide el usuario
+  (regla CLAUDE.md) — este comando no toca versiones.

package/comandos/swl/release.md

@@ -266,7 +266,19 @@ Usar tags anotados siempre (regla del skill).
 
 ## Paso 9 — Generar RELEASE-NOTES
 
-Crea `RELEASE-NOTES-v[nueva-versión].md` con: resumen, cambios, instrucciones de actualización y guía de migración si hay breaking changes.
+Crea `releases/v[nueva-versión]/RELEASE-NOTES-v[nueva-versión].md` con: resumen,
+cambios, instrucciones de actualización y guía de migración si hay breaking changes.
+
+```bash
+mkdir -p releases/v[nueva-versión]
+# escribir releases/v[nueva-versión]/RELEASE-NOTES-v[nueva-versión].md
+```
+
+**NUNCA crear las RELEASE-NOTES en la raíz del repo.** La convención (todos los
+releases previos en `releases/`) es que las RELEASE-NOTES viven SOLO en
+`releases/vX.Y.Z/` — no se versiona ninguna copia en raíz. El directorio
+`releases/v[nueva-versión]/` también lo crea `evidencia-release.js` (Paso 9.5);
+si ese paso corre primero, el `mkdir -p` es no-op.
 
 ## Paso 9.5 — Evidencia de procedencia (cadena de suministro, ADR-0038)
 
@@ -286,20 +298,21 @@ Esto escribe (vía `scripts/lib/evidencia-release.js`):
 Luego:
 
 1. **Insertar la sección "Integridad y verificación"** en
-   `RELEASE-NOTES-v[nueva-versión].md`, justo después de la sección de
-   correcciones. La genera `seccionVerificacionNotas` de la lib:
+   `releases/v[nueva-versión]/RELEASE-NOTES-v[nueva-versión].md`, justo después de
+   la sección de correcciones. La genera `seccionVerificacionNotas` de la lib:
 
    ```bash
    node -e "const {seccionVerificacionNotas}=require('./scripts/lib/evidencia-release');const fs=require('fs');const v='[nueva-versión]';const sums=fs.readFileSync('releases/v'+v+'/SHA256SUMS','utf8').trim().split(/\s+/);const md=seccionVerificacionNotas({version:v,hash:sums[0],tarball:sums[1]});console.log(md)"
    ```
 
-   Copiar ese markdown a RELEASE-NOTES (tras "Correcciones").
+   Anexar ese markdown a `releases/v[nueva-versión]/RELEASE-NOTES-v[nueva-versión].md`
+   (tras "Correcciones").
 
-2. **Copiar las RELEASE-NOTES** a la carpeta del release como evidencia
-   versionada:
+2. **Versionar la evidencia** del release. Las RELEASE-NOTES ya viven en
+   `releases/v[nueva-versión]/` (Paso 9) — NO hacer `cp` desde la raíz (no debe
+   existir copia en raíz):
 
    ```bash
-   cp RELEASE-NOTES-v[nueva-versión].md releases/v[nueva-versión]/
    git add releases/v[nueva-versión]/
    ```
 
@@ -397,7 +410,7 @@ Commits incluidos: [N] (feat: [N], fix: [N], otros: [N])
 Tests: [ejecutados OK | omitidos (--skip-tests)]
 
 Próximos pasos:
-  1. Revisar RELEASE-NOTES-v[nueva-versión].md
+  1. Revisar releases/v[nueva-versión]/RELEASE-NOTES-v[nueva-versión].md
   2. git push origin v[nueva-versión]
   3. Publicar release en GitHub/GitLab si aplica
   4. Notificar al equipo
@@ -416,6 +429,15 @@ Próximos pasos:
   release ya creado pero aún-no-publicado obliga a mover el tag + regenerar la
   evidencia (el SHA del tarball cambia si el commit toca archivos de
   `package.json#files`) — churn evitable. Si hay que iterar, hacerlo antes de taggear.
+- **Si el usuario alimenta archivos de forma incremental para la MISMA versión
+  ("faltan N archivos que agregar a esta versión, espera"), NO finalizar el
+  release** (no congelar tag, no regenerar evidencia final, no proponer push)
+  hasta que el usuario confirme que ya están TODOS los archivos. Mantener el
+  commit de release como HEAD entre tandas para que cada incorporación sea un
+  `amend` limpio + mover tag; regenerar la evidencia (SBOM/SHA256SUMS) SOLO en la
+  última tanda, porque el SHA del tarball cambia con cada archivo nuevo que entre
+  en `package.json#files`. Cerrar el release antes de tiempo obliga a rehacer
+  evidencia y tag por cada archivo tardío.
 - **El agente NUNCA corre `npm` (test/pack/build/publish) en paralelo a un
   `npm run publish:*` que está ejecutando el usuario.** `test:release` incluye
   `test:smoke` (install/uninstall a temp + lectura de estado global); dos suites