@saulwade/swl-ses 1.6.1 → 1.6.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@saulwade/swl-ses",
-  "version": "1.6.1",
-  "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot con 60 agentes, 162 habilidades, 44 comandos, 67 reglas y 41 hooks. Soporta 11 lenguajes y 7 runtimes: Claude Code, OpenClaude, OpenCode, Gemini CLI, Cursor, Codex CLI (soporte completo); GitHub Copilot (soporte parcial). 100% en espanol (Mexico). Multi-target install (--target CSV / --all-runtimes), autoconfig MCP en Cursor/Codex con --with-mcp, agentes Codex en TOML, hooks Cursor (17 eventos) y Codex (6 eventos). Gateway bidireccional con relay Telegram y auditoria profunda Nemesis con loop evaluator-optimizer opt-in (ADR-0021) y 8 tools ejecutables. v1.6.1 endurece el verificador docs-vs-codigo con gates de profundidad (Check #2 + #6 + #7 + #8 nuevos) y formaliza el protocolo proactivo de propagacion (doc-sync v1.3.0) — ADR-0023.",
+  "version": "1.6.5",
+  "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot con 61 agentes, 177 habilidades, 44 comandos, 69 reglas y 42 hooks. Soporta 11 lenguajes y 7 runtimes: Claude Code, OpenClaude, OpenCode, Gemini CLI, Cursor, Codex CLI (soporte completo); GitHub Copilot (soporte parcial). 100% en espanol (Mexico). Multi-target install (--target CSV / --all-runtimes), autoconfig MCP en Cursor/Codex con --with-mcp, agentes Codex en TOML, hooks Cursor (17 eventos) y Codex (6 eventos). Gateway bidireccional con relay Telegram y auditoria profunda Nemesis con loop evaluator-optimizer opt-in (ADR-0021) y 8 tools ejecutables. v1.6.5 integra 3 patrones de awesome-codex-skills (ComposioHQ, MIT) — agent-deep-links + changelog-generator + gh-fix-ci-swl — ADR-0029, y promueve 3 evoluciones SIGAF al sistema global (D1 nemesis SendMessage + D2 verificar smoke frontend + L2 alineacion veredicto).",
   "bin": {
     "swl-ses": "bin/swl-ses.js",
     "swl-telegram-bot": "bin/swl-telegram-bot.js",
@@ -28,7 +28,7 @@
   ],
   "scripts": {
     "postinstall": "echo '\n  swl-software-engineering-system instalado.\n  Ejecuta: npx swl-ses init\n'",
-    "test": "node --test tests/lib/*.test.js tests/scripts/*.test.js tests/scripts/lib/*.test.js tests/scripts/tui/*.test.js tests/hooks/*.test.js tests/gateway/*.test.js tests/bin/*.test.js tests/transformadores/*.test.js tests/mcp-server/*.test.js",
+    "test": "node --test tests/lib/*.test.js tests/scripts/*.test.js tests/scripts/lib/*.test.js tests/scripts/tui/*.test.js tests/hooks/*.test.js tests/hooks/lib/*.test.js tests/habilidades/*.test.js tests/gateway/*.test.js tests/bin/*.test.js tests/transformadores/*.test.js tests/mcp-server/*.test.js",
     "test:validate": "node scripts/validar.js",
     "test:manifest": "node scripts/validar-manifest.js",
     "test:docs": "node scripts/verificar-docs-vs-codigo.js",

package/plugin.json

@@ -1,28 +1,34 @@
 {
   "name": "swl-ses",
-  "version": "1.6.1",
-  "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot. 60 agentes, 162 habilidades, 44 comandos, 67 reglas y 41 hooks. 62 librerias. 11 lenguajes. Soporta Claude Code, Copilot, OpenCode, Codex y Gemini CLI. Loop evaluator-optimizer en /swl:nemesis (ADR-0021). v1.6.1 endurece verificador docs-vs-codigo (gates de profundidad) y formaliza protocolo proactivo doc-sync v1.3.0 (ADR-0023).",
+  "version": "1.6.5",
+  "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot. 61 agentes, 177 habilidades, 44 comandos, 69 reglas y 42 hooks. 62 librerias. 11 lenguajes. Soporta Claude Code, Copilot, OpenCode, Codex y Gemini CLI. Loop evaluator-optimizer en /swl:nemesis (ADR-0021). 3 patrones de awesome-codex-skills (ComposioHQ, MIT) adoptados (ADR-0029) — agent-deep-links + changelog-generator + gh-fix-ci-swl. Promueve 3 evoluciones SIGAF (D1 nemesis SendMessage, D2 verificar smoke frontend, L2 alineacion veredicto).",
   "author": "Saul Wade Leon",
   "license": "MIT",
   "repository": "https://github.com/saul-wade/swl-ses",
   "skills": [
     "habilidades/accesibilidad-a11y",
     "habilidades/agent-browser",
+    "habilidades/agent-deep-links",
     "habilidades/agentes-como-servicio",
     "habilidades/ai-runtime-security",
     "habilidades/angular-avanzado",
     "habilidades/angular-moderno",
     "habilidades/api-rest-diseno",
+    "habilidades/aprender-de-git-diff",
     "habilidades/aprendizaje-continuo",
     "habilidades/async-python",
     "habilidades/auth-patrones",
     "habilidades/auto-evolucion-protocolo",
     "habilidades/autoresearch",
     "habilidades/azure-cloud",
+    "habilidades/backend-async-postgres-testing",
+    "habilidades/backend-error-design",
     "habilidades/backend-mcp-servidor",
     "habilidades/backend-production-resilience",
     "habilidades/benchmark-memoria",
     "habilidades/brainstorming",
+    "habilidades/browser-interaction-patterns",
+    "habilidades/browser-research-domains",
     "habilidades/build-errors-cpp",
     "habilidades/build-errors-csharp",
     "habilidades/build-errors-go",
@@ -34,6 +40,7 @@
     "habilidades/build-errors-rust",
     "habilidades/build-errors-swift",
     "habilidades/build-errors-typescript",
+    "habilidades/changelog-generator",
     "habilidades/checklist-calidad",
     "habilidades/checklist-seguridad",
     "habilidades/checkpoints-verificacion",
@@ -127,6 +134,13 @@
     "habilidades/prevencion-racionalizacion",
     "habilidades/prevencion-sobreingenieria",
     "habilidades/privacy-memoria",
+    "habilidades/proceso-autoverificacion-evidencias",
+    "habilidades/proceso-confianza-pre-implementacion",
+    "habilidades/proceso-ddia-fundamentos",
+    "habilidades/proceso-ddia-streaming",
+    "habilidades/proceso-discovery-machote",
+    "habilidades/proceso-intent-engineering",
+    "habilidades/proceso-modular-split",
     "habilidades/prompt-engineering",
     "habilidades/protocolo-revision-swl",
     "habilidades/rag-arquitectura",
@@ -134,6 +148,7 @@
     "habilidades/react-experto",
     "habilidades/react-optimizacion",
     "habilidades/redis-experto",
+    "habilidades/reducir-entropia",
     "habilidades/release-semver",
     "habilidades/rust-experto",
     "habilidades/rust-patrones",
@@ -193,6 +208,7 @@
     "agentes/frontend-react-swl.md",
     "agentes/frontend-swl.md",
     "agentes/frontend-tailwind-swl.md",
+    "agentes/gh-fix-ci-swl.md",
     "agentes/implementador-swl.md",
     "agentes/investigador-swl.md",
     "agentes/investigador-ux-swl.md",

package/reglas/arquitectura.md

@@ -274,6 +274,44 @@ Documentar en un ADR qué patrón se usa y por qué.
 
 ---
 
+## Split modular con compositor por herencia múltiple
+
+Cuando un módulo backend (router, service, repository) supera ~1500 LOC en un
+solo archivo y contiene sub-dominios identificables, aplicar el playbook de
+split documentado en `Skill("proceso-modular-split")`. El patrón clave:
+
+- **Compositor por herencia múltiple, NO `__getattr__`**: el compositor (clase
+  monolítica que mantiene API pública previa) hereda de cada sub-service. MRO
+  inspeccionable, type checker feliz, IDE autocompleta. `__getattr__` para
+  delegación es opaco al tipado y al stack trace.
+
+- **Helpers transversales en clase base, no duplicados entre sub-services**: si
+  un helper como `_validar_predio_existe` lo usan ≥80% de sub-services, vive
+  en `<modulo>/service_base.py` (`<Modulo>ServiceBase`). Cada sub-service
+  hereda de la base. Si solo lo usan 1-2 sub-services, vive en uno de ellos y
+  los demás importan por composición (no por herencia).
+
+- **Helper transversal cross-sub-service NO se duplica**: validación que
+  aparece en ≥3 sub-services es candidata inmediata a la clase base. La
+  duplicación es señal de que el split fue prematuro o de que se perdió el
+  helper común durante la migración.
+
+- **Validar a escala**: el patrón se validó a ~20,000 LOC totales en SIGM
+  (recaudación ADR-0016 + catastro ADR-0017). Aplicar al primer módulo es
+  prudente; antes de aplicar a un tercero, confirmar que el feedback de los
+  dos primeros no requiere ajuste al playbook.
+
+Anti-patrones a evitar (las auditorías técnicas NO los detectan):
+
+- Router que importa el compositor cuando existe sub-service específico.
+- Router que accede a `servicio._repo` o métodos privados del sub-service.
+- Default `None` pasado explícitamente bypasea el default del callee.
+- CLAUDE.md y AGENTS.md desincronizados tras el refactor.
+
+Estos los detecta revisión de arquitectura humana o senior, no `nemesis-auditor-swl`.
+
+---
+
 ## Reglas de desempate entre principios (conflict resolution)
 
 Los principios de ingeniería pueden entrar en tensión. Cuando dos reglas

package/reglas/arreglar-al-detectar.md

@@ -86,6 +86,99 @@ principio:
   reportan", "p95 > 60s en producción documentado", "uso > N veces/mes",
   no "cuando sea relevante" o "más adelante".
 
+### Hallazgos colaterales con blast radius alto — patrón Hallazgo A/B/C
+
+Durante el trabajo principal puedes detectar un problema secundario cuyo fix
+**no cabe** en la regla general "detectar → informar → arreglar en mismo
+turno" porque su blast radius es alto: toca infra compartida, requiere
+downtime, modifica contratos públicos, exige decisión arquitectural, o su
+remediación dura más que el trabajo principal en curso.
+
+Aplicar el catálogo de tres opciones explícitas — NUNCA mezclar el fix con
+el trabajo principal sin etiquetarlo y NUNCA dejarlo como deuda silenciosa.
+
+#### Definición operacional
+
+Un hallazgo colateral cumple **al menos uno** de estos atributos:
+
+- Su fix toca archivos fuera del scope del trabajo principal (>3 archivos
+  no relacionados con la tarea actual).
+- Requiere operación destructiva (`git filter-branch`, `git filter-repo`,
+  drop de tabla, rotación de credencial productiva).
+- Modifica configuración de infra compartida (CI/CD, branch protection,
+  permisos de repo, secrets de organización).
+- Exige decisión arquitectural ambigua que el agente no puede tomar solo.
+- Su remediación dura más que el commit actual del trabajo principal.
+
+Si NO cumple ninguno de estos atributos, NO es Hallazgo A/B/C — aplicar la
+regla general (arreglar en mismo turno).
+
+#### Las tres opciones explícitas
+
+| Opción | Cuándo | Acción |
+|---|---|---|
+| **Hallazgo A — Resolver ahora** | Fix < 30 min, reversible con `git revert`, sin blast radius en infra compartida, sin decisión arquitectural | Pausar trabajo principal, fix en commit separado etiquetado, retomar |
+| **Hallazgo B — DT formal con trigger verificable** | Fix con blast radius alto pero NO bloqueante para el trabajo principal. Tiene criterio observable que define cuándo cerrarlo | Redactar entry en `.planning/DEUDA-TECNICA.md` con ID, trigger verificable, plan de cierre paso a paso. Continuar trabajo principal |
+| **Hallazgo C — Escalar al usuario** | Fix excede autorización del agente: requiere decisión arquitectural, operación destructiva irreversible, o modifica contratos productivos | Pausar trabajo principal, reportar al usuario con 3 opciones concretas y recomendación, esperar decisión explícita |
+
+#### Reglas duras
+
+- **Reportar siempre, independientemente de la opción elegida**: el usuario
+  ve el hallazgo en el mismo turno, no se entera en el commit posterior.
+- **DT formal NO es "lo apunto y veremos"**: requiere ID (`DT-NOMBRE-X`),
+  trigger verificable observable, plan de cierre con pasos concretos, y
+  entry visible en `.planning/DEUDA-TECNICA.md` commiteada en mismo turno.
+- **NUNCA degradar Hallazgo C a Hallazgo B sin pedirlo**: una decisión
+  arquitectural disfrazada de DT es deuda silenciosa con cara de proceso.
+- **NUNCA "arreglar como parte del trabajo principal" un Hallazgo B/C
+  sin etiquetarlo**: aunque el fix sea pequeño, si su blast radius es alto
+  el commit debe ser separado con mensaje explícito ("colateral: cierra
+  DT-X" o "colateral: aplica fix urgente fuera de scope original").
+
+#### Ejemplo validado (SIGAF, sesión 2026-05-20)
+
+Durante implementación de pipeline DevSecOps (gates gitleaks + SAST + deps
++ containers), el agente detectó tres hallazgos colaterales:
+
+- **Hallazgo A — Validator JWT con frozenset + regex**: bug detectado en
+  `backend/app/core/config.py` donde `_CENTINELA` hardcodeado divergía del
+  `.env.example` real. Fix < 30 min, reversible, alcance acotado a
+  validators. Aplicado en commit separado mismo turno + 8 tests de regresión.
+
+- **Hallazgo B — DT-GHAS-HABILITAR**: detectado que repo PRIVATE en
+  organización sin GitHub Advanced Security responde 403 al upload SARIF.
+  Mitigación inmediata con `continue-on-error: true` en step de upload.
+  DT formal con trigger verificable: "equipo crece >2 personas, auditoría
+  externa, o licencia GHAS adquirida". Entry en `.planning/DEUDA-TECNICA.md`
+  con plan de cierre (eliminar `continue-on-error` cuando GHAS activo).
+
+- **Hallazgo C — DT-HISTORIAL-ENV**: detectado que commit `203a603` en
+  historial git contenía `ADMIN_PASSWORD=Admin2026!` (ya rotado, ya en
+  `.gitignore`, pero presente en `git log -p`). Fix requiere `git
+  filter-branch` o `git filter-repo` (destructivo, irreversible para
+  colaboradores con clones locales). El agente escaló al usuario; usuario
+  respondió "estamos en desarrollo y etapa de pruebas" → degradado a DT
+  formal con trigger "antes del primer deploy productivo, repo público
+  o colaborador externo".
+
+Los tres hallazgos quedaron visibles, etiquetados y con trigger observable.
+Ninguno se mezcló silenciosamente con el trabajo principal del pipeline.
+
+#### Anti-patrones específicos
+
+- **"Lo arreglo de paso porque ya estoy aquí"**: si el fix tiene blast
+  radius alto, NO va de paso. Va etiquetado o no va.
+- **DT sin trigger verificable**: "cuando sea posible", "más adelante",
+  "cuando tengamos tiempo" — viola la regla general arriba. Trigger debe
+  ser condición observable.
+- **Reportar Hallazgo C como informativo sin pedir decisión**: si la
+  decisión requiere autorización del usuario, la respuesta NO es
+  "documentado para tu consideración" — es "elige A, B o C".
+- **Aplicar Hallazgo A descubriendo en medio que era Hallazgo C**: si al
+  empezar el fix detectas que tiene blast radius mayor del estimado,
+  detente, revierte el WIP, y re-clasifica. NO terminar "porque ya
+  empezamos".
+
 ---
 
 ## Excepciones legítimas

package/reglas/auditorias-documentales-estructurales.md

@@ -112,6 +112,44 @@ agent-browser, @dbml/core, likec4, etc.) debe documentarse en
 7. **Limitaciones conocidas**.
 8. **Origen** (ADR, sesión, paper, repo).
 
+### Para prosa cuantificada en campos descriptivos de manifiestos JSON
+
+Los campos `description` de `package.json` y `plugin.json` contienen prosa
+con cifras agregadas del sistema (típicamente "60 agentes + N habilidades +
+M comandos + K reglas + L hooks"). Esa prosa es **fuente de verdad parcial
+para usuarios de npm y de Claude Code marketplace** — npm muestra el
+description en la página del paquete; Claude Code lo lee al listar plugins.
+
+Estos campos NO son agregados estructurales que los gates estándar
+auditen (los gates escanean `.md` y comparan contra `INVENTARIO.md`),
+por lo que necesitan tratamiento explícito:
+
+1. **Universo a chequear**: `package.json#description` Y `plugin.json#description`.
+   Ambos deben extraerse, parsearse para sus cifras, y compararse entre sí.
+
+2. **Verificación cross-manifest**: las cifras de
+   `package.json#description` deben coincidir letra por letra con las de
+   `plugin.json#description`. Cualquier divergencia es bug de manifiesto
+   inconsistente.
+
+3. **Verificación vs fuente de verdad estructural**: las cifras de ambos
+   manifiestos deben coincidir con los conteos reales que reporta
+   `INVENTARIO.md` (regenerado por `node scripts/generar-inventario.js`).
+
+4. **Gate automatizado**: `scripts/verificar-release.js` incluye gate
+   "Gate de description" desde v1.6.4 que ejecuta exactamente esa
+   triple validación. Confiar en su exit code antes de release.
+
+**Anti-patrón documentado**: actualizar `plugin.json#description` con
+cifras nuevas tras agregar 2 skills, asumir que `package.json#description`
+está alineado por simetría, y commitear sin verificar. Origen del bug
+v1.6.4 (sesión 2026-05-18): el commit del ADR-0028 actualizó
+`plugin.json#description` (171/69/42 + ADR-0028) pero dejó
+`package.json#description` con valores stale de v1.6.2 (162/67/41 +
+ADR-0025). Los 4 gates pre-existentes no lo detectaron porque ninguno
+escaneaba campos JSON descriptivos. El gate dedicado se agregó tras este
+bug; la regla queda anti-recurrente.
+
 ---
 
 ## Procedimiento al ejecutar una auditoría documental

package/reglas/fragmentos-compartidos.md

@@ -150,3 +150,29 @@ Para extraer un bloque duplicado a fragmento:
 - [ ] No es contenido invocable dinámicamente (eso es skill)
 - [ ] Cada agente que lo usa lo declara en `fragmentos: [...]`
 - [ ] `scripts/validar-manifest.js` no reporta errores
+
+## Implicaciones en scripts de auditoría/conteo de agentes
+
+Cualquier script o hook que recorre `agentes/*.md` para contar o validar
+agentes DEBE excluir fragmentos explícitamente con
+`filter(f => f.endsWith('.md') && !f.startsWith('_'))`. Si no lo hace,
+incluye fragmentos en el conteo y reporta cifras incorrectas o falla en la
+validación de frontmatter (los fragmentos NO tienen frontmatter de agente).
+
+Scripts y hooks SWL que aplican esta exclusión y deben mantenerla:
+
+- `scripts/validar.js` — verifica frontmatter de agentes.
+- `scripts/validar-manifest.js` — cruza `agentes/*.md` vs `modulos.json`.
+- `scripts/generar-inventario.js` — cuenta agentes para INVENTARIO/SALUD.
+- `hooks/validar-intent-spec.js` — regex `/\/agentes\/[^_][^/]*\.md$/`
+  con clase negada para fragmentos.
+- Cualquier script futuro de auditoría de agentes.
+
+**Caso de regresión histórico**: tras crear `agentes/_intent-spec.md`
+(fragmento) en sesión 2026-05-18, `scripts/generar-inventario.js` contó
+61 agentes cuando real eran 60 (gate `verificar-release.js` lo detectó).
+Fix: agregar el filtro al `readdirSync` del script.
+
+**Consideración futura**: centralizar la lógica en
+`scripts/lib/listar-agentes.js` con la exclusión por defecto evitaría que
+el filtro se omita en scripts nuevos.

package/reglas/intent-engineering.md

@@ -0,0 +1,214 @@
+# Regla: Intent Engineering para agentes ALTO riesgo
+
+Esta regla es **OBLIGATORIA** y aplica al crear, modificar o promover agentes
+del sistema SWL cuyo `nivelRiesgo` sea `ALTO`. Implementa el framework
+"Intent Engineering" de 8 partes de Pawel Huryn (*Lead Agents Like Humans*,
+Product Compass, 2026-05).
+
+---
+
+## Principio
+
+> Un agente con autonomía elevada que opera sin intent specification explícito
+> falla silenciosamente por instrucciones ambiguas, deriva de scope o pérdida
+> de health metrics. Los agentes ALTO riesgo del sistema SWL DEBEN declarar
+> las 8 partes del framework de forma verificable (frontmatter + fragmento),
+> no implícita.
+
+Huryn lo resume:
+
+> "Agents don't fail because the model is weak. They fail because intent is
+> incomplete. Objectives are vague. Outcomes are implicit. Trade-offs are
+> unstated. Constraints are treated as suggestions. Autonomy is granted
+> without understanding risk." (Lead Agents Like Humans, línea 56)
+
+SWL adopta el framework parcialmente: las partes 5 (Org Context) y 3
+(Desired Outcomes) viven en `CLAUDE.md` y `PLAN.md` respectivamente, no en
+cada agente. Las otras 6 son responsabilidad del autor del agente.
+
+---
+
+## Cuándo aplicar
+
+OBLIGATORIO al:
+
+- Crear un agente nuevo `nivelRiesgo: ALTO`.
+- Modificar el frontmatter de un agente `nivelRiesgo: ALTO` existente.
+- Promover un agente de `MEDIO` o `BAJO` a `ALTO`.
+- Auditar agentes con `/swl:revisar` cuando se detecta deriva de scope.
+
+NO aplicar al:
+
+- Agentes `BAJO` o `MEDIO` riesgo (los campos son opcionales para ellos).
+- Cambios cosméticos al cuerpo markdown del agente sin tocar frontmatter.
+- Skills, hooks, comandos (la regla aplica solo a agentes).
+
+---
+
+## Lo que DEBE declarar un agente ALTO
+
+### En el frontmatter YAML
+
+```yaml
+nivelRiesgo: ALTO            # Parte 7 — Autonomy Boundaries
+maxTurnos: <int>             # Parte 8 — Stop Rules (cap iteraciones)
+strategy: "<1-3 lineas>"     # Parte 1 — Strategy (max 500 chars)
+healthMetrics:               # Parte 4 — qué NO debe degradar
+  - "<invariante 1>"
+  - "<invariante 2>"
+steering:                    # Parte 6 — prompt-level constraints
+  - "<guía de comportamiento o @reglas/X.md>"
+hardGuardrails:              # Parte 6 — orchestration-level constraints
+  - "<restricción enforced por hook/schema o @reglas/X.md>"
+fragmentos:
+  - _intent-spec             # Importa el bloque compartido al system prompt
+```
+
+### En el cuerpo markdown
+
+NO requerido pero recomendado: agregar sección breve "Health Metrics" o
+"Constraints" si el rol del agente justifica explicación adicional.
+
+---
+
+## Criterios de calidad por campo
+
+### `strategy:`
+
+- 1-3 líneas, máximo 500 caracteres.
+- Nombra el tradeoff que el agente prioriza.
+- NO es boilerplate genérico ("código limpio", "buenas prácticas").
+- Hereda del proyecto cuando aplica; declara explícito cuando el rol impone
+  tradeoffs propios.
+
+**Ejemplo válido** (`migrador-swl`):
+```yaml
+strategy: >
+  Preservar integridad de datos por encima de velocidad de migración.
+  Expand-contract obligatorio sobre cambios destructivos. Rollback siempre
+  viable. Sin downtime es preferible a migración rápida.
+```
+
+**Ejemplo inválido**:
+```yaml
+strategy: "Migrar datos de forma segura."   # boilerplate genérico
+```
+
+### `healthMetrics:`
+
+- Lista de invariantes blandas que el agente protege mientras trabaja.
+- Distintas de `outcomes`: outcomes se persiguen, health metrics se
+  protegen.
+- Sin métrica = sin protección. Agentes ALTO sin health metrics violan
+  Goodhart's Law por construcción.
+- Pueden ser cualitativas si no hay telemetría que las mida live ("sin
+  warnings nuevos de ORM").
+
+### `steering:`
+
+- Soft constraints. El agente las lee como guía.
+- Acepta texto inline o referencia a regla global (`@reglas/X.md`).
+- NO duplicar contenido de `@reglas/X.md` — referenciar evita drift.
+
+### `hardGuardrails:`
+
+- Hard constraints aplicadas por arquitectura (hooks, schemas, sandbox).
+- Cada item DEBE referenciar el mecanismo que enforza:
+  - `@reglas/seguridad-agentes.md § Privilegio mínimo` (regla global)
+  - `@hooks/proteccion-rutas.js` (hook bloqueante)
+  - `@schemas/agent-frontmatter.schema.json#properties.tools` (validación)
+- Si la restricción no tiene mecanismo de enforcement, NO es hard
+  guardrail — es steering.
+
+---
+
+## Excepciones legítimas
+
+NO aplica la regla cuando:
+
+1. **El agente acaba de bajar de ALTO a MEDIO/BAJO**: si en una revisión se
+   determina que un agente puede operar con menos privilegio, primero baja
+   el `nivelRiesgo`, luego los campos se vuelven opcionales.
+
+2. **El agente está en proceso de deprecación**: agentes marcados
+   `evolvable: false` con plan de retiro documentado en ADR pueden quedar
+   sin las 8 partes hasta su retiro. Documentar excepción en commit.
+
+3. **Refactor cosmético reversible**: cambios al cuerpo markdown que no
+   modifican `nivelRiesgo:` ni los 4 campos nuevos no disparan la regla.
+
+---
+
+## Cómo verificar conformidad
+
+### Manualmente
+
+Para auditar un agente ALTO:
+
+```bash
+node -e "
+const a = require('js-yaml').load(require('fs').readFileSync(process.argv[1], 'utf-8').match(/^---\n([\s\S]+?)\n---/)[1]);
+if (a.nivelRiesgo !== 'ALTO') { console.log('NO-ALTO'); return; }
+const faltan = ['strategy','healthMetrics','steering','hardGuardrails'].filter(k => !a[k]);
+if (faltan.length) console.error('FALTAN:', faltan.join(','));
+else console.log('OK');
+" agentes/X-swl.md
+```
+
+### Automáticamente
+
+Hook `hooks/validar-intent-spec.js` (creado en F3) ejecuta esta validación
+en PostToolUse sobre `Write|Edit` de `agentes/*.md`. Modo inicial:
+`blocking: false` (warn-only). Promoción a `blocking: true` tras 2 semanas
+estables sin falsos positivos, documentada en ADR-0027.
+
+---
+
+## Anti-patrones
+
+- **Declarar `steering` algo que requiere enforcement**: "no eliminar
+  archivos" sin hook que lo prevenga. Si importa, va en `hardGuardrails`
+  con apoyo arquitectural.
+- **Copiar `@reglas/X.md` completa en `hardGuardrails`**: referenciar, no
+  duplicar. La regla evoluciona; la copia se queda atrás.
+- **Health metrics como outcomes negados**: "latencia < 200ms" es outcome;
+  "no degradar latencia mientras trabajas" es health metric.
+- **Strategy demasiado vaga**: si la strategy aplica a cualquier agente,
+  no es strategy de este agente. Borrar o especificar.
+- **Promover a ALTO sin declarar las 6 partes**: violación directa de
+  esta regla; el hook F3 (cuando blocking=true) lo previene.
+
+---
+
+## Relación con otras reglas
+
+- `reglas/seguridad-agentes.md § Privilegio mínimo` — los campos nuevos NO
+  escalan privilegios; son metadata declarativa.
+- `reglas/fragmentos-compartidos.md` — el `_intent-spec` importado es un
+  fragmento legítimo.
+- `reglas/skills-estandar.md` — los skills cargables (`proceso-intent-engineering`)
+  son la versión on-demand del fragmento.
+- `reglas/registro-componentes-nuevos.md` — al agregar agente nuevo ALTO,
+  registrar en manifiestos sigue siendo obligatorio.
+
+---
+
+## Cargar para aprender el framework
+
+```
+Skill("proceso-intent-engineering")
+```
+
+El skill explica cada parte con ejemplos, mapea Huryn (4 tiers) a SWL (3
+tiers), enumera anti-patrones y entrega tabla de referencia rápida.
+
+---
+
+## Origen
+
+Regla creada el 2026-05-18 como parte de Opción B (ver ADR-0025). Cubre el
+gap detectado en análisis del artículo Huryn: SWL cubría 5/8 partes pero
+no enforzaba sistemáticamente las 3 restantes (Strategy, Health Metrics,
+Constraints distinguidas). La regla aplica solo a agentes ALTO porque
+costos de declaración no compensan en agentes BAJO/MEDIO (los 6 agentes
+del CONTEXTO original que eran BAJO/MEDIO se dejan opcionales).

package/reglas/registro-componentes-nuevos.md

@@ -46,6 +46,7 @@ listados según el tipo:
 | **Schema** (`schemas/X.schema.json`) | `INVENTARIO.md`, `SALUD.md`. Si valida frontmatter de algún componente, actualizar `scripts/validar.js` para que lo use | `node scripts/generar-inventario.js` |
 | **Plantilla** (`plantillas/X.md`) | `manifiestos/modulos.json` si la copia el instalador, `INVENTARIO.md` | `node scripts/generar-inventario.js` |
 | **Bump de versión** (`package.json`) | 15+ ubicaciones — usar checklist en `/swl:release` paso 6, ejecutar `node scripts/verificar-release.js` para verificar sincronización | `node scripts/verificar-release.js` |
+| **Cifras en `description` de manifiestos** (cualquier cambio de conteo de agentes / skills / comandos / reglas / hooks) | **Ambos** `package.json#description` Y `plugin.json#description` con cifras nuevas. **NO tocar uno sin tocar el otro.** Adicionalmente: la frase "60 agentes + N habilidades + M comandos + K reglas + L hooks" en `README.md`, `CLAUDE.md`, `MANUAL_USO.md`, `COMANDOS.md`, `INSTALACION.md`, `MAPEO_SKILLS_AGENTES.md` debe actualizarse con las cifras nuevas. | `node scripts/verificar-release.js` (gate "description" detecta drift cross-manifest + drift vs INVENTARIO.md) |
 
 **Ambos manifiestos cuando aplique** son obligatorios. Si un hook se registra
 solo en `.claude/settings.json` pero no en `manifiestos/hooks-config.json`, el
@@ -133,6 +134,19 @@ Falso. La regla `git-workflow.md` exige commits atómicos. Un componente
 nuevo + su registro = un commit atómico. Mezclar varios componentes nuevos
 en un commit es violación separada.
 
+### Description stale de un manifiesto que el otro sí actualizó
+
+Olvidar editar `package.json#description` cuando se actualizó
+`plugin.json#description` (o viceversa). Origen del bug v1.6.4: el commit del
+ADR-0028 actualizó `plugin.json#description` con cifras nuevas (171 skills, 69
+reglas, 42 hooks, ADR-0028) pero dejó `package.json#description` con valores
+de v1.6.2 (162/67/41, ADR-0025). El gate de versión no lo detectó porque solo
+chequea `version`; el gate de contadores no lo detectó porque solo escanea
+`.md`. Ahora hay gate dedicado (`ejecutarGateDescription` en
+`scripts/verificar-release.js`) que detecta drift cross-manifest. Antes de
+commitear cualquier cambio que afecte conteos, ejecutar
+`node scripts/verificar-release.js` y mirar la sección "Gate de description".
+
 ### Confiar en `node -e` para validar conteos sin re-leer manifiestos
 
 Falso. `node -e "console.log(require('./plugin.json').skills.length)"`
@@ -181,6 +195,43 @@ commit separado del fix actual.
 
 ---
 
+## Citas a módulos de manifest en ADRs y docs
+
+Cuando un ADR o documento del sistema cita un nombre de módulo de
+`manifiestos/modulos.json`, `manifiestos/hooks-config.json` o
+`manifiestos/perfiles.json`, **el nombre DEBE verificarse contra el
+archivo real antes de persistir el ADR/doc**. Citas redactadas "de
+memoria" tienden a inventar nombres plausibles que no existen.
+
+**Patrón verificador**:
+
+```bash
+# Verificar en qué módulo está registrado un componente específico
+node -e "
+const m = require('./manifiestos/modulos.json');
+for (const [k, v] of Object.entries(m.modulos || m)) {
+  if (v.archivos && v.archivos.includes('hooks/<NOMBRE>.js')) {
+    console.log('Módulo real:', k);
+  }
+}
+"
+
+# Listar todos los nombres de módulos disponibles
+node -e "console.log(Object.keys(require('./manifiestos/modulos.json').modulos))"
+```
+
+**Caso de regresión histórico**: ADR-0027 (2026-05-18) inicialmente decía
+"`manifiestos/modulos.json` en módulo `hooks-evolucion-instintos`" —
+módulo **inexistente**. El hook real quedó en `hooks-core`. Pasó la
+primera revisión porque el ADR se redactó de memoria. Fix retrospectivo
+en commit `6919b01`.
+
+**Aplicación**: la regla global `~/.claude/rules/verificar-citas-normativas.md
+§ Familia 2` cubre "citas archivo:línea" — esta regla extiende el patrón
+al dominio interno del proyecto: citas a nombres de módulos en manifiestos.
+
+---
+
 ## Checklist antes de commitear un componente nuevo
 
 - [ ] El archivo del componente está en el directorio correcto (`agentes/`, `habilidades/`, `comandos/swl/`, etc.).
@@ -190,3 +241,4 @@ commit separado del fix actual.
 - [ ] `npm run test:all` pasa sin errores.
 - [ ] Si es release: `node scripts/verificar-release.js` pasa sin discrepancias.
 - [ ] El commit message menciona qué componente se agrega y, si aplica, en qué módulo.
+- [ ] Si el ADR/doc cita un módulo de manifest, el nombre se verificó con `node -e` o `grep` contra el archivo real (no escrito "de memoria").