@saulwade/swl-ses 1.0.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saulwade/swl-ses",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot con 59 agentes, 151 habilidades, 42 comandos, 60 reglas y 37 hooks. Soporta 11 lenguajes y 5 runtimes: Claude Code, Copilot, OpenCode, Codex y Gemini CLI. 100% en espanol (Mexico). Incluye gateway bidireccional con relay Telegram a Claude Code.",
   "bin": {
     "swl-ses": "bin/swl-ses.js",
@@ -31,9 +31,10 @@
     "test:smoke": "node scripts/smoke-test.js",
     "test:aislamiento": "node scripts/validar-tests-aislamiento.js",
     "test:all": "npm test && node scripts/validar.js && node scripts/validar-manifest.js",
-    "test:release": "npm run test:all && npm run test:smoke",
+    "test:userland": "node scripts/validar-userland-vacio.js",
+    "test:release": "npm run test:all && npm run test:userland && npm run test:smoke",
     "doctor": "node scripts/doctor.js",
-    "prepack": "node scripts/limpiar-artefactos-python.js",
+    "prepack": "node scripts/limpiar-artefactos-python.js && node scripts/validar-userland-vacio.js",
     "prepublishOnly": "npm run test:release",
     "publish:all": "node scripts/publicar.js",
     "publish:github": "node scripts/publicar.js --solo-github",
@@ -76,9 +77,6 @@
   "dependencies": {
     "docx": "^9.6.1"
   },
-  "optionalDependencies": {
-    "@xenova/transformers": "^2.17.2"
-  },
   "overrides": {
     "pako": "^2.1.0",
     "readable-stream": "^4.7.0"

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "swl-ses",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot. 59 agentes, 151 habilidades, 42 comandos, 60 reglas y 37 hooks. 60 librerias. 11 lenguajes. Soporta Claude Code, Copilot, OpenCode, Codex y Gemini CLI.",
   "author": "Saul Wade Leon",
   "license": "MIT",

package/reglas/arquitectura.md

@@ -214,6 +214,26 @@ de abstracciones (protocolos, interfaces, clases abstractas).
 
 ---
 
+## Tres capas de reutilización: regla, skill, fragmento
+
+El sistema SWL distingue tres capas para evitar duplicación. La elección de la
+capa correcta depende de cuándo y cómo se carga el contenido:
+
+- **Regla** (`reglas/X.md`): política global cargada por matcher de archivos.
+  Aplicable a múltiples agentes y skills. Ejemplo: `reglas/seguridad.md`.
+- **Skill** (`habilidades/X/SKILL.md`): conocimiento operacional invocado
+  dinámicamente con `Skill("X")`. Tiene frontmatter, descripción y carga
+  bajo demanda. Ejemplo: `habilidades/tdd-workflow/SKILL.md`.
+- **Fragmento** (`agentes/_X.md`): bloque de prompt compartido por varios
+  agentes que se incrusta literalmente en su system prompt. Sin overhead
+  runtime, sin frontmatter operacional, no routable por el orquestador.
+  Ejemplo: `agentes/_hitl-alto-riesgo.md`.
+
+Antes de crear texto compartido entre agentes, decidir cuál capa aplica. Ver
+`reglas/fragmentos-compartidos.md` para la convención completa.
+
+---
+
 ## DRY — Don't Repeat Yourself
 
 Si una regla de negocio, una validación, un cálculo o una transformación cambia,

package/reglas/fragmentos-compartidos.md

@@ -0,0 +1,152 @@
+# Regla: Fragmentos compartidos no-routables
+
+Esta regla es **OBLIGATORIA** para autores y mantenedores de agentes y reglas
+del sistema SWL. Define un tercer tier entre reglas y skills: bloques de prompt
+compartidos que se incrustan literalmente en agentes/reglas para eliminar
+duplicación textual sin convertirse en componentes invocables.
+
+---
+
+## El problema que resuelve
+
+Hoy cuando dos agentes necesitan repetir el mismo párrafo (protocolo HITL para
+nivelRiesgo ALTO, anti-fallback silencioso, regla de paralelización, mención
+de "aplica brevedad-output"), las opciones existentes son:
+
+| Mecanismo | Problema |
+|-----------|----------|
+| Copiar y pegar el bloque | Drift textual: una copia se actualiza, la otra no. |
+| Convertirlo en regla obligatoria | Las reglas son globales (cargadas por matchers), no se incrustan literal en un agente concreto. |
+| Convertirlo en skill | Las skills se invocan dinámicamente con `Skill("nombre")` y consumen tokens; un fragmento de 6 líneas no justifica el overhead. |
+| Convertirlo en agente | Los agentes son routables; un guard compartido no debe aparecer en la tabla de routing del orquestador. |
+
+Faltaba una capa para "texto compartido que vive en el system prompt del agente,
+sin overhead runtime ni routing". Esta regla la formaliza.
+
+---
+
+## Convención
+
+### Ubicación y naming
+
+| Tipo | Ubicación | Naming |
+|------|-----------|--------|
+| Fragmento para agentes | `agentes/_*.md` | prefijo `_`, kebab-case, **sin sufijo `-swl`** |
+| Fragmento para reglas | `reglas/_fragmentos/_*.md` | prefijo `_`, kebab-case |
+
+**Ejemplos válidos**:
+- `agentes/_hitl-alto-riesgo.md`
+- `agentes/_anti-fallback-silencioso.md`
+- `agentes/_brevedad-output-ref.md`
+- `reglas/_fragmentos/_descarga-progresiva.md`
+
+**Ejemplos inválidos**:
+- `agentes/_scope-guard-swl.md` (no usar sufijo `-swl` — no es un agente)
+- `agentes/scope_guard.md` (snake_case prohibido)
+- `agentes/_ScopeGuard.md` (camelCase prohibido)
+
+### Reglas duras
+
+1. **NO routable**: el orquestador NO incluye `agentes/_*.md` en su tabla de
+   rutas. El prefijo `_` señala al loader que ese archivo es un fragmento, no
+   un agente. La validación `scripts/validar-manifest.js` rechaza si un
+   `agentes/_*.md` aparece en `manifiestos/modulos.json` como agente.
+
+2. **NO invocable**: no se carga con `Skill("...")`. No tiene frontmatter
+   `name`/`description` ni schema. Es texto puro Markdown.
+
+3. **Importación declarativa via frontmatter**: el agente que usa el fragmento
+   lo declara en su frontmatter:
+   ```yaml
+   fragmentos: [_hitl-alto-riesgo, _anti-fallback-silencioso]
+   ```
+   El campo `fragmentos` está definido en `schemas/agent-frontmatter.schema.json`.
+   El loader (al cargar el agente) lee cada fragmento referenciado y lo concatena
+   al final del system prompt.
+
+4. **Tamaño máximo 100 líneas**: si un fragmento crece más, probablemente debe
+   ser una regla obligatoria o una skill. Los fragmentos son párrafos, no
+   documentos.
+
+5. **Sin frontmatter operacional**: el archivo `_*.md` puede tener un comentario
+   YAML opcional al inicio con metadata humana (autor, agentes que lo usan), pero
+   NO tiene campos como `nivelRiesgo` o `permisosRed` — los hereda del agente
+   que lo importa.
+
+6. **Auditoría obligatoria**: cuando se crea un fragmento, el script
+   `scripts/validar-manifest.js` verifica que el fragmento es referenciado por
+   ≥2 agentes. Un fragmento usado por un solo agente no justifica su existencia
+   y debe re-incrustarse en el agente.
+
+---
+
+## Cuándo crear un fragmento
+
+✅ Crear cuando:
+- El mismo bloque de ≥3 líneas aparece literalmente en ≥3 agentes.
+- El bloque es estructural (protocolo, regla operativa) — no contenido de
+  dominio variable.
+- Cambiar el bloque en el futuro debe propagarse a todos los agentes.
+
+❌ NO crear cuando:
+- El texto solo aparece en 1-2 agentes (no hay ahorro real).
+- El bloque ya existe como regla obligatoria (cargada por matcher).
+- El comportamiento se invoca dinámicamente (eso es una skill).
+- Es un párrafo de menos de 80 caracteres (no justifica el overhead de gestión).
+
+---
+
+## Diferencia con reglas y skills
+
+| Capa | Cuándo carga | Cómo se usa | Ejemplo |
+|------|-------------|-------------|---------|
+| **Regla** (`reglas/X.md`) | Por matcher cuando se tocan ciertos archivos | Cargada al contexto global de la sesión | `reglas/seguridad.md` aplica a `*.py`, `auth/`, etc. |
+| **Skill** (`habilidades/X/SKILL.md`) | Cuando un agente invoca `Skill("X")` | Carga bajo demanda, contiene instrucciones operativas | `habilidades/tdd-workflow/SKILL.md` |
+| **Fragmento** (`agentes/_X.md`) | Al cargar un agente que lo declara en `fragmentos` | Se incrusta literalmente en system prompt — sin overhead runtime | `agentes/_hitl-alto-riesgo.md` |
+
+Los fragmentos son la opción más barata: cero tokens runtime adicional, máxima
+consistencia textual entre agentes que comparten un bloque.
+
+---
+
+## Migración desde duplicación existente
+
+Para extraer un bloque duplicado a fragmento:
+
+1. **Identificar**: con `Grep` confirmar que el texto aparece literal en ≥3 agentes.
+2. **Crear** el archivo `agentes/_nombre.md` con el bloque en el estado más
+   reciente/completo de las copias existentes.
+3. **Reemplazar** en cada agente la duplicación por una referencia mínima:
+   ```markdown
+   <!-- fragmento: _nombre -->
+   ```
+   El loader sustituye este marcador por el contenido del fragmento al cargar.
+4. **Declarar** en el frontmatter del agente:
+   ```yaml
+   fragmentos: [_nombre]
+   ```
+5. **Verificar** con `node scripts/validar-manifest.js` que el fragmento está
+   referenciado por ≥2 agentes.
+6. **Commit atómico**: `refactor(fragmentos): extraer X a _nombre — usado en N agentes`.
+
+---
+
+## Origen y referencias
+
+- Patrón inspirado en `_scope-guard.md` de Bug-Bounty-Agents
+  (https://github.com/anthropics/bug-bounty-agents) — convención `_` como
+  shared prompt block no-routable.
+- Decisión documentada en ADR-XXX (ver `.planning/adrs/`).
+- Schema: `schemas/agent-frontmatter.schema.json` campo `fragmentos`.
+
+---
+
+## Checklist antes de crear un fragmento
+
+- [ ] El texto aparece literal en ≥3 agentes
+- [ ] El nombre sigue convención `_kebab-case.md` (sin sufijo `-swl`)
+- [ ] Tamaño ≤100 líneas
+- [ ] No reemplaza a una regla obligatoria existente
+- [ ] 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

package/reglas/gobernanza.md

@@ -32,7 +32,16 @@ Los skills generados por `auto-evolucion-swl` o `/swl:evolucionar`:
 - Requieren validación en al menos 3 sesiones de trabajo independientes
   antes de ser promovidos al perfil `completo`.
 - Deben pasar la verificación de `/swl:salud` sin degradar el score actual.
-- La promoción se registra en `.planning/AUDITORIA.md` con justificación.
+- **Gate G8 — evidencia de calidad obligatoria**: antes de mover un skill
+  desde `_userland/plugins/` a `habilidades/`, ejecutar
+  `/swl:evaluar-skill <nombre>` y exigir badge ≥ **Plata** (score ≥ 70).
+  Skills con Bronce o sin badge se devuelven a `_userland/` con feedback
+  de qué dimensiones bajan el score. Detalle del flujo en
+  `agentes/auto-evolucion-swl.md` sección "Gate G8". Origen ADR 0013
+  sección 3C.
+- La promoción se registra en `.planning/AUDITORIA.md` con justificación
+  Y en `.planning/evolucion/evoluciones.jsonl` con evento
+  `tipo: "promocion-skill"` y `score`.
 
 ### Reglas nuevas obligatorias
 

package/reglas/seguridad-agentes.md

@@ -34,6 +34,18 @@ Cada agente recibe exclusivamente los permisos que necesita para su función.
 - Un agente sin `permisosComandos` no debe ejecutar Bash bajo ninguna circunstancia.
 - El `toolBudget` limita la cantidad de herramientas por invocación. Agentes
   con presupuesto `simple` (1-3 tools) no deben recibir tareas que requieran más.
+- El `maxTurnos` (definido en `schemas/agent-frontmatter.schema.json`) declara
+  el tope explícito de iteraciones (tool calls) que el agente puede ejecutar
+  antes de pausar y escalar. **OBLIGATORIO** declararlo en frontmatter para
+  agentes con patrón evaluator-optimizer, recovery catalog, debugging
+  iterativo, o cualquier loop autónomo. Valores recomendados según patrón
+  observado: thin orchestrator/QA lineal: 10; debugging iterativo: 12;
+  implementación con write-complete-test-once: 15; release multi-fase: 18;
+  auto-evolución con gates G1-G8: 20; migración expand-contract: 25.
+  Agentes one-shot (revisores, documentadores, diseñadores) NO requieren
+  `maxTurnos` — son no-iterativos por diseño. Patrón inspirado en *Building
+  Effective AI Agents* (Anthropic, p.10) — "stopping conditions, maximum
+  number of iterations".
 
 ### Anti-escalación en cadenas de delegación
 

package/reglas/skills-estandar.md

@@ -239,6 +239,25 @@ CLAUDE.md el orquestador no sabe que existe.
 
 ---
 
+## Diferencia con fragmentos compartidos
+
+Las skills NO son la única capa de reutilización del sistema SWL. Existen tres
+capas distintas — cada una con su propósito:
+
+| Capa | Cuándo usar | Cómo se carga |
+|------|-------------|---------------|
+| **Regla** (`reglas/X.md`) | Política transversal aplicable por matcher de archivos | Carga global cuando el matcher se cumple |
+| **Skill** (`habilidades/X/SKILL.md`) | Conocimiento operacional invocable bajo demanda | Carga al invocar `Skill("X")` |
+| **Fragmento** (`agentes/_X.md`) | Bloque de texto compartido por ≥3 agentes en su system prompt | Se incrusta literalmente al cargar el agente — sin overhead runtime |
+
+NO crear una skill cuando el contenido es:
+- Texto compartido entre múltiples agentes que no se invoca dinámicamente → es fragmento.
+- Política aplicable a archivos del codebase → es regla.
+
+Ver `reglas/fragmentos-compartidos.md` para la convención completa de fragmentos.
+
+---
+
 ## Convención de naming para skills nuevos
 
 Todo skill nuevo DEBE usar prefijo de dominio. Facilita agrupación lógica sin

package/reglas/usar-context7.md

@@ -0,0 +1,226 @@
+# Regla: Consultar Context7 antes de generar código con dependencias externas
+
+Esta regla es OBLIGATORIA para todo agente o skill del sistema SWL que
+genere código que use librerías, frameworks, SDKs o APIs externas. La regla
+se carga automáticamente para los agentes de stack (`backend-*-swl`,
+`frontend-*-swl`, `mobile-*-swl`, `implementador-swl`, `llm-apps-swl`,
+`pagos-swl`, `datos-swl`) y para skills de implementación.
+
+---
+
+## Por qué existe esta regla
+
+El conocimiento del modelo sobre librerías de terceros tiene fecha de
+corte. Una librería que en el corte estaba en la versión X y era la
+recomendación, hoy puede estar:
+
+- En una versión Y mayor con cambios incompatibles
+- Deprecada y reemplazada por otra librería
+- Con vulnerabilidades conocidas que requieren un parche
+- Renombrada o migrada a otra organización
+
+Generar código sin verificar la versión actual genera tres clases de
+defectos en producción:
+
+1. **Imports a APIs deprecadas** que arrastran warnings o se eliminan
+   en próximas versiones (ejemplo histórico: `@xenova/transformers`
+   migrado a `@huggingface/transformers`).
+2. **Dependencias transitivas obsoletas** que el usuario ve como
+   warnings al instalar (ejemplo: `prebuild-install@7.1.3` arrastrada
+   por una librería que el sistema eligió sin verificar la salud).
+3. **Vulnerabilidades CVE conocidas** que están parchadas en versiones
+   más nuevas que el modelo no conoce.
+
+Context7 (MCP `mcp__claude_ai_Context7__query-docs` y
+`mcp__claude_ai_Context7__resolve-library-id`) provee documentación
+actualizada de librerías y frameworks. Su uso es la primera línea de
+defensa contra estos tres problemas.
+
+---
+
+## Cuándo consultar Context7 (OBLIGATORIO)
+
+Antes de:
+
+1. **Agregar una nueva dependencia** a `package.json`, `requirements.txt`,
+   `pom.xml`, `Cargo.toml`, `go.mod`, `composer.json`, `Package.swift` o
+   equivalente.
+2. **Generar código que importe o use una librería externa** que no
+   estaba ya en uso en el proyecto, aunque la librería ya esté
+   instalada.
+3. **Actualizar la versión** de una dependencia existente.
+4. **Migrar de una librería a otra** alternativa (ej.
+   `axios` → `fetch`, `moment` → `date-fns`, `jest` → `vitest`).
+5. **Resolver un warning de deprecación** de una dependencia
+   transitiva.
+6. **Implementar un patrón nuevo** del framework (ej. Server Actions
+   en Next.js, Signals en Angular, Suspense en React) — la API
+   correcta cambia rápido.
+
+NO es necesario consultar Context7 cuando:
+
+- La librería es interna al proyecto SWL (`scripts/lib/*`,
+  `hooks/lib/*`).
+- Es la biblioteca estándar del lenguaje (Node `fs`, Python `os`).
+- Es código que no usa dependencias externas (algoritmos, lógica de
+  negocio sin librerías de terceros).
+- El cambio es trivial (renombrar variable, formatear).
+
+---
+
+## Cómo consultar Context7
+
+El MCP de Context7 expone dos herramientas principales:
+
+```
+mcp__claude_ai_Context7__resolve-library-id(libraryName)
+  → Resuelve un nombre de librería (ej. "react", "next.js") al ID
+    canónico que Context7 usa internamente.
+
+mcp__claude_ai_Context7__query-docs(library, topic, version?)
+  → Devuelve documentación actualizada de la librería sobre el
+    topic específico. Acepta versión opcional.
+```
+
+Flujo típico:
+
+1. Resolver el ID de la librería:
+   ```
+   const id = mcp__claude_ai_Context7__resolve-library-id({
+     libraryName: "next.js"
+   });
+   ```
+
+2. Consultar el tema específico:
+   ```
+   const docs = mcp__claude_ai_Context7__query-docs({
+     library: id,
+     topic: "Server Actions",
+     version: "16"
+   });
+   ```
+
+3. Verificar:
+   - ¿La librería sigue siendo la recomendada o está deprecada?
+   - ¿Hay una alternativa migrada que deberíamos usar?
+   - ¿La API que voy a generar es la actual o cambió?
+   - ¿La versión que recomienda Context7 coincide con la del
+     `package.json` del proyecto?
+
+---
+
+## Reglas estrictas
+
+### NUNCA agregar dependencia sin verificar
+
+Antes de escribir `npm install <paquete>`, `pip install <paquete>`,
+`go get <paquete>` o equivalente:
+
+- Consultar Context7 para confirmar que la librería sigue activa.
+- Confirmar la versión más reciente compatible con el resto del
+  stack del proyecto.
+- Si Context7 reporta deprecación, **NO la uses**. Buscar la
+  alternativa migrada.
+
+### NUNCA generar código con API obsoleta
+
+Si el usuario pide implementar X usando librería Y:
+
+- Consultar Context7 sobre cómo se hace X en la versión actual de Y.
+- Si la API que aparece en el contexto del modelo difiere de la que
+  Context7 reporta como actual, **usar la de Context7**.
+- Documentar en un comentario corto la versión consultada y la
+  fecha si la API es notable.
+
+### NUNCA copiar ejemplos de la web sin verificar versión
+
+Stack Overflow, blogs y tutoriales tienen alta probabilidad de
+mostrar código deprecado. Si el agente consulta una web (vía
+WebSearch o WebFetch) y obtiene un ejemplo, ese ejemplo debe
+validarse contra Context7 antes de incorporarlo.
+
+---
+
+## Excepción: Context7 no responde o no tiene la librería
+
+Si Context7 no tiene documentación disponible para una librería
+específica:
+
+1. **Documentar en el código** que Context7 no respondió y la API se
+   tomó de la fuente oficial (npm registry, docs del repo).
+2. **Verificar al menos**: la librería existe, no está deprecada en
+   npm/PyPI, su última publicación es reciente (≤ 12 meses).
+3. **NO bloquear** el flujo del usuario por este caso — proceder con
+   diligencia razonable.
+
+---
+
+## Auditoría retroactiva
+
+Esta regla aplica también al código existente del proyecto SWL:
+
+- Si durante un refactor se detecta una dependencia que arrastra
+  warnings de deprecación, abrir un ticket para auditarla con
+  Context7 y migrar si hay alternativa actual.
+- El comando `/swl:auditar-deps` (cuando esté disponible) debe
+  cruzar las dependencias del proyecto contra Context7 para
+  detectar deprecaciones silenciosas.
+
+---
+
+## Aplicabilidad por agente
+
+| Agente | Aplica | Cuándo |
+|---|---|---|
+| `backend-python-swl` | SÍ | Al generar código FastAPI/Django/SQLAlchemy |
+| `backend-node-swl` | SÍ | Al generar código Express/Fastify/NestJS |
+| `backend-java-swl` | SÍ | Al generar código Spring Boot/JPA |
+| `backend-go-swl` | SÍ | Al generar código Go con frameworks |
+| `backend-rust-swl` | SÍ | Al generar código Axum/Actix |
+| `backend-csharp-swl` | SÍ | Al generar código ASP.NET Core |
+| `frontend-react-swl` | SÍ | Al generar código React/Next.js |
+| `frontend-angular-swl` | SÍ | Al generar código Angular |
+| `frontend-css-swl` | SÍ | Al usar PostCSS/Tailwind plugins |
+| `frontend-tailwind-swl` | SÍ | Al usar Tailwind v4+ APIs |
+| `frontend-swl` | SÍ | Al usar Vue/Svelte/Lit |
+| `mobile-android-swl` | SÍ | Al usar Jetpack Compose libs |
+| `mobile-ios-swl` | SÍ | Al usar SwiftUI/Combine |
+| `mobile-cross-swl` | SÍ | Al usar React Native/Flutter |
+| `implementador-swl` | SÍ | Generalista — siempre |
+| `llm-apps-swl` | SÍ | LangChain, OpenAI SDK, Anthropic SDK |
+| `pagos-swl` | SÍ | Stripe SDK actualizado |
+| `datos-swl` | SÍ | ORMs y drivers de BD |
+| `arquitecto-swl` | RECOMENDADO | Al evaluar tradeoffs entre librerías |
+| `revisor-codigo-swl` | RECOMENDADO | Al detectar deps deprecadas en review |
+| `revisor-seguridad-swl` | OBLIGATORIO | Al verificar CVEs de dependencias |
+| Resto de agentes | NO | No generan código con dependencias externas |
+
+---
+
+## Checklist de consulta Context7
+
+Antes de marcar una tarea como completa:
+
+- [ ] ¿Las dependencias agregadas/usadas se verificaron contra Context7?
+- [ ] ¿La versión usada está alineada con la que Context7 reporta como actual?
+- [ ] ¿No hay imports de APIs deprecadas según Context7?
+- [ ] ¿Las dependencias transitivas conocidas no son warnings de
+      deprecación al instalar?
+- [ ] Si Context7 no tenía la librería, ¿se documentó el motivo?
+
+---
+
+## Origen de esta regla
+
+Esta regla se formalizó tras observar en la primera instalación pública
+de `@saulwade/swl-ses@1.0.0` (2026-04-30) un warning de
+`prebuild-install@7.1.3 deprecated` arrastrado por
+`@xenova/transformers` que estaba en `optionalDependencies`. La
+dependencia se eligió en una iteración anterior sin verificar Context7;
+la migración oficial era `@huggingface/transformers`. El warning se vio
+en cada `npm install` del paquete distribuido. Resuelto en v1.0.1
+eliminando la dependencia opcional y elevando esta regla a obligatoria
+para que no se repita.
+
+Memoria asociada: `feedback_usar_context7.md` (preferencia previa del
+usuario, formalizada como regla).

package/schemas/agent-frontmatter.schema.json

@@ -143,6 +143,24 @@
       "type": "array",
       "items": { "type": "string" },
       "description": "Situaciones donde este agente NO debe invocarse aunque parezca relevante superficialmente. Campo propio de swl-ses; previene activacion tangencial (agent hijacking) por similitud de terminos en description. Equivalente estructural de la seccion 'Cuando NO invocarme' en el cuerpo, legible por herramientas de analisis sin parsear markdown. Aditivo, no breaking, aplicable a agentes con evolvable:false (metadata defensiva, no evolucion AGP — ver ADR-0004)."
+    },
+    "fase": {
+      "type": "string",
+      "enum": ["discover", "plan", "implement", "verify", "release", "learn", "meta", "cross"],
+      "description": "Fase del SDLC en que opera el agente. Vocabulario controlado para routing deterministico del orquestador sin parsear description. discover=research/UX/discovery; plan=arquitectura/planificacion; implement=codigo/implementacion; verify=revision/testing/seguridad; release=deploy/release; learn=auto-evolucion/aprendizaje; meta=componentes del sistema SWL mismo; cross=transversal a varias fases. Aditivo, opcional. Inspirado en patron Phase de Bug-Bounty-Agents/AGENTS.md y patron Workflow-vs-Agent del articulo Anthropic 'Building Effective AI Agents'."
+    },
+    "dominio": {
+      "type": "string",
+      "enum": ["backend", "frontend", "mobile", "data", "infra", "security", "ux", "quality", "docs", "process", "meta", "general"],
+      "description": "Dominio tecnico primario del agente. Vocabulario controlado para filtrado y matching. backend=APIs/servidores; frontend=UI/web; mobile=Android/iOS/cross; data=BD/ETL/datos; infra=cloud/CI/devops; security=auditoria/OWASP; ux=diseno/usabilidad; quality=tests/QA/code review; docs=documentacion; process=workflow/orquestacion; meta=sistema SWL; general=transversal. Aditivo, opcional."
+    },
+    "fragmentos": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^_[a-z][a-z0-9-]*$"
+      },
+      "description": "Lista de bloques de prompt compartidos no-routables (archivos agentes/_*.md) que este agente importa literalmente en su system prompt. Permite centralizar texto repetido entre multiples agentes sin duplicacion. Los fragmentos NO son skills (no se invocan dinamicamente) ni agentes (no son routables por el orquestador). Convencion: prefijo _ en kebab-case, sin sufijo -swl. Ejemplo: ['_brevedad-output-ref', '_hitl-alto-riesgo']. Inspirado en patron _scope-guard.md de Bug-Bounty-Agents."
     }
   },
   "additionalProperties": true

package/scripts/auditar-agentes-gaps.js

@@ -24,6 +24,14 @@
 var fs = require('fs');
 var path = require('path');
 
+// Escritura atómica obligatoria (regla CLAUDE.md). Fallback defensivo.
+var atomicWriteJSON;
+try {
+  atomicWriteJSON = require(path.join(__dirname, '..', 'hooks', 'lib', 'atomic-write.js')).atomicWriteJSON;
+} catch (_) {
+  atomicWriteJSON = function (p, o) { fs.writeFileSync(p, JSON.stringify(o, null, 2), 'utf8'); };
+}
+
 var RAIZ_AGENTES = path.resolve(__dirname, '..', 'agentes');
 var DESTINO_PLANNING = path.resolve(
   __dirname, '..', '.planning', 'evolucion', 'audit-agentes-gaps.json'
@@ -140,7 +148,7 @@ if (argv.indexOf('--resumen') !== -1) {
 } else if (argv.indexOf('--save') !== -1) {
   var dir = path.dirname(DESTINO_PLANNING);
   fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(DESTINO_PLANNING, JSON.stringify(resultado, null, 2), 'utf8');
+  atomicWriteJSON(DESTINO_PLANNING, resultado);
   imprimirResumen(resultado);
   process.stderr.write('Inventario persistido en: ' + DESTINO_PLANNING + '\n');
 } else {

package/scripts/auditar-cobertura-frameworks.js

@@ -25,6 +25,14 @@
 const fs = require('fs');
 const path = require('path');
 
+// Escritura atómica obligatoria (regla CLAUDE.md). Fallback defensivo.
+let atomicWriteJSON;
+try {
+  ({ atomicWriteJSON } = require(path.join(__dirname, '..', 'hooks', 'lib', 'atomic-write.js')));
+} catch {
+  atomicWriteJSON = (p, o) => fs.writeFileSync(p, JSON.stringify(o, null, 2), 'utf8');
+}
+
 const RAIZ_SKILLS = path.resolve(__dirname, '..', 'habilidades');
 const DESTINO = path.resolve(
   __dirname, '..', '.planning', 'evolucion', 'cobertura-frameworks.json'
@@ -232,7 +240,7 @@ if (argv.includes('--resumen')) {
 } else if (argv.includes('--save')) {
   const dir = path.dirname(DESTINO);
   fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(DESTINO, JSON.stringify(resultado, null, 2), 'utf8');
+  atomicWriteJSON(DESTINO, resultado);
   imprimirResumen(resultado);
   process.stderr.write(`Inventario persistido en: ${DESTINO}\n`);
 } else {

package/scripts/auditar-skills-gaps.js

@@ -20,6 +20,14 @@
 const fs = require('fs');
 const path = require('path');
 
+// Escritura atómica obligatoria (regla CLAUDE.md). Fallback defensivo.
+let atomicWriteJSON;
+try {
+  ({ atomicWriteJSON } = require(path.join(__dirname, '..', 'hooks', 'lib', 'atomic-write.js')));
+} catch {
+  atomicWriteJSON = (p, o) => fs.writeFileSync(p, JSON.stringify(o, null, 2), 'utf8');
+}
+
 const RAIZ_SKILLS = path.resolve(__dirname, '..', 'habilidades');
 const DESTINO_PLANNING = path.resolve(
   __dirname, '..', '.planning', 'evolucion', 'audit-skills-gaps.json'
@@ -197,7 +205,7 @@ if (argv.includes('--resumen')) {
 } else if (argv.includes('--save')) {
   const dir = path.dirname(DESTINO_PLANNING);
   fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(DESTINO_PLANNING, JSON.stringify(resultado, null, 2), 'utf8');
+  atomicWriteJSON(DESTINO_PLANNING, resultado);
   imprimirResumen(resultado);
   process.stderr.write(`Inventario persistido en: ${DESTINO_PLANNING}\n`);
 } else {

package/scripts/bootstrap-instintos.js

@@ -30,6 +30,16 @@ const CWD = process.cwd();
 const APRENDIZAJES_PATH = path.join(CWD, '.planning', 'APRENDIZAJES.md');
 const INSTINTOS_PATH = path.join(CWD, 'instintos', 'proyecto.yaml');
 
+// Escritura atómica obligatoria — instintos/proyecto.yaml es el catálogo
+// vivo de instintos del proyecto; corromperlo equivale a perder la memoria
+// inductiva del sistema. Fallback defensivo si el módulo no está disponible.
+let atomicWriteSync;
+try {
+  ({ atomicWriteSync } = require(path.join(CWD, 'hooks', 'lib', 'atomic-write.js')));
+} catch {
+  atomicWriteSync = (p, c, e) => fs.writeFileSync(p, c, e);
+}
+
 const flags = {
   write: process.argv.includes('--write'),
   force: process.argv.includes('--force'),
@@ -250,7 +260,7 @@ function main() {
   }
 
   const yaml = serializarYaml(instintos);
-  fs.writeFileSync(INSTINTOS_PATH, yaml, 'utf8');
+  atomicWriteSync(INSTINTOS_PATH, yaml, 'utf8');
   console.log(`\nOK: ${instintos.length} instintos escritos en ${INSTINTOS_PATH}`);
 }