@saulwade/swl-ses 1.7.4 → 1.9.0

package/reglas/arquitectura.evolved.json

@@ -0,0 +1,7 @@
+{
+  "evolved": true,
+  "evolved-from": "1.8.0",
+  "evolved-at": "2026-06-04",
+  "evolved-by": "evolucionar",
+  "evolved-note": "PE-010 sección nueva 'Tablas append-only — excepción documentada a audit columns nullable=False'. Patrón portable a logs estructurados, audit trails, event sourcing, telemetría. Origen: OIC v1.5 Slice 1 2026-06-04 (BitacoraError)."
+}

package/reglas/arquitectura.md

@@ -274,6 +274,71 @@ Documentar en un ADR qué patrón se usa y por qué.
 
 ---
 
+## Tablas append-only — excepción documentada a "audit columns nullable=False"
+
+Algunas tablas son **append-only por diseño**: solo se crean filas (INSERT) y
+eventualmente se eliminan por purga (DELETE). Nunca se actualizan. Ejemplos
+típicos: logs de errores (`bitacora_error`, `error_log`), audit trails inmutables,
+telemetría, métricas históricas, event sourcing event store, outbox pattern.
+
+Para estas tablas la regla general del proyecto "`created_by`/`updated_by`
+`nullable=False` en tablas transaccionales" **NO aplica**. Documentar la
+excepción explícitamente:
+
+1. En el **docstring de la clase modelo** (Python/Java/C#):
+
+```python
+class BitacoraError(Base):
+    """
+    Registro inmutable de un error backend o frontend.
+
+    Tabla append-only: solo se crean filas (INSERT) y se purgan por antigüedad
+    (DELETE). Nunca se actualizan. Esta invariante es fundamental para que el
+    log de errores sea un audit trail confiable.
+
+    Excepción a regla "audit columns nullable=False":
+        La convención del proyecto exige `created_by` y `updated_by` NOT NULL
+        en tablas transaccionales. BitacoraError queda exenta porque:
+        (a) Es un log del sistema, no una entidad de negocio modificable.
+        (b) No tiene `updated_at` ni `updated_by` — no hay concepto de
+            "última modificación" en una tabla append-only.
+        (c) `usuario_id` es nullable de forma intencional: los errores de
+            sesiones no autenticadas (401 antes del login) no tienen usuario.
+    """
+```
+
+2. En el **comentario del DDL SQL**:
+
+```sql
+COMMENT ON TABLE bitacora_error IS
+    'Errores backend y frontend persistidos para diagnóstico. '
+    'Append-only: solo INSERT y DELETE (purga). '
+    'Sin updated_at/updated_by por diseño (excepción documentada en CONTEXTO).';
+```
+
+3. En el **GRANT** del rol de aplicación, omitir explícitamente `UPDATE`:
+
+```sql
+-- INSERT: para que el sistema cree entradas.
+-- SELECT: para que el admin las consulte.
+-- DELETE: para que el job de purga elimine antiguas.
+-- NO UPDATE: la tabla es append-only por diseño.
+GRANT SELECT, INSERT, DELETE ON bitacora_error TO ine_user;
+```
+
+**Criterios para considerar una tabla append-only legítima**:
+
+- Toda fila representa un evento ocurrido en un momento específico (immutable in time).
+- No hay caso de negocio que requiera modificar la fila después de creada.
+- La única forma de "corregir" un dato erróneo es insertar una fila correctora
+  posterior (event sourcing) o purgar y re-insertar (telemetría).
+- El borrado se hace por política de retención (antigüedad), no por revocación.
+
+**Origen del patrón**: OIC v1.5 Slice 1 (2026-06-04). Patrón portable a cualquier
+proyecto con logs estructurados, audit trails o event sourcing.
+
+---
+
 ## Split modular con compositor por herencia múltiple
 
 Cuando un módulo backend (router, service, repository) supera ~1500 LOC en un

package/reglas/gobernanza.md

@@ -40,7 +40,7 @@ Los skills generados por `auto-evolucion-swl` o `/swl:evolucionar`:
   `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
+  Y en `.planning/evolution/evoluciones.jsonl` con evento
   `tipo: "promocion-skill"` y `score`.
 
 ### Reglas nuevas obligatorias

package/reglas/memoria-consolidada.md

@@ -15,7 +15,7 @@ regla clara, un mismo dato puede terminar en el lugar incorrecto o duplicado.
 | 2 | **`.planning/APRENDIZAJES.md`** | Markdown con entradas `### [YYYY-MM-DD] Título` agrupadas por sección | Conocimiento del dominio (anti-patrones, patrones, decisiones, gotchas) |
 | 3 | **`instintos/proyecto.yaml` / `global.yaml` / `perfil-usuario.yaml`** | YAML estructurado con confidence, scope, evidence_count | Patrones aprendidos inductivamente, con promoción/degradación |
 | 4 | **`.planning/sessions/search-index.json`** | Índice FTS de sesiones pasadas | Búsqueda histórica de trabajo (qué se hizo, cuándo) |
-| 5 | **`.planning/evolucion/*`** | JSONL (nudges, agentes) + JSON (métricas, alertas, evoluciones) | Estado del ciclo de auto-evolución |
+| 5 | **`.planning/evolution/*`** | JSONL (nudges, agentes) + JSON (métricas, alertas, evoluciones) | Estado del ciclo de auto-evolución |
 
 ---
 
@@ -44,11 +44,11 @@ regla clara, un mismo dato puede terminar en el lugar incorrecto o duplicado.
 
 | Tipo de dato | Canal correcto |
 |---|---|
-| Nudge emitido por un hook | 5 (`.planning/evolucion/nudges.jsonl`) |
-| Evento de subagente terminado | 5 (`.planning/auto-evolucion/agentes.jsonl`) |
-| Evolución aplicada/revertida a skill | 5 (`.planning/evolucion/evoluciones.jsonl`) |
-| Alerta persistente (nudges ignorados) | 5 (`.planning/evolucion/alertas-persistentes.json`) |
-| Métricas agregadas (health score) | 5 (`.planning/evolucion/metricas.json`) |
+| Nudge emitido por un hook | 5 (`.planning/evolution/nudges.jsonl`) |
+| Evento de subagente terminado | 5 (`.planning/auto-evolution/agentes.jsonl`) |
+| Evolución aplicada/revertida a skill | 5 (`.planning/evolution/evoluciones.jsonl`) |
+| Alerta persistente (nudges ignorados) | 5 (`.planning/evolution/alertas-persistentes.json`) |
+| Métricas agregadas (health score) | 5 (`.planning/evolution/metricas.json`) |
 | Traza de ejecución de agente | `.planning/traces/` (OTLP-lite) |
 | Audit trail inmutable | `.planning/audit.jsonl` + Merkle |
 
@@ -125,7 +125,7 @@ conocido, datos en canales deprecados.
 
 - **Corrección del usuario escrita a APRENDIZAJES.md** → debe ir al perfil
 - **Anti-patrón técnico escrito al perfil del usuario** → debe ir a APRENDIZAJES
-- **Métrica persistida en APRENDIZAJES.md** → debe ir a `.planning/evolucion/`
+- **Métrica persistida en APRENDIZAJES.md** → debe ir a `.planning/evolution/`
 - **Secreto/credencial en cualquier canal** → bloqueo inmediato (`privacy-memoria`)
 - **Dato duplicado en proyecto.yaml y global.yaml** → uno debe borrarse
   (promover a global SOLO cuando confidence > 0.8 Y validado cross-proyecto)

package/reglas/seguridad.evolved.json

@@ -0,0 +1,7 @@
+{
+  "evolved": true,
+  "evolved-from": "1.8.0",
+  "evolved-at": "2026-06-04",
+  "evolved-by": "evolucionar",
+  "evolved-note": "PE-003 (verificación de flags antes de asumir servicios externos LDAP/Redis/S3) + PE-004 (sanitización PII centralizada en handlers) + PE-007 (generación de passwords legibles sin chars ambiguos). Origen: OIC v1.5 2026-06-04, bug histórico manuel.monteagudo + Slice 2 v1.5 Observabilidad."
+}

package/reglas/seguridad.md

@@ -141,6 +141,147 @@ vulnerabilidad del OWASP Top 10. Las más frecuentes en este stack:
 
 ---
 
+## Verificación obligatoria de flags de configuración antes de asumir servicios externos
+
+Toda rama de código que asuma un servicio externo opcional (LDAP, Redis, S3, SMTP,
+OIDC, Auth0, etc.) DEBE verificar el flag de configuración del proyecto ANTES de
+tomar la decisión. Sin esta verificación, una configuración no esperada deja a los
+usuarios atrapados en flujos rotos sin error visible.
+
+**Anti-patrón** (caso real OIC 2026-06-04, dos bugs históricos en el mismo flujo):
+
+```python
+# MAL — asume LDAP siempre habilitado
+if rol == "ADMIN":
+    hashed = hash_password(body.password)
+else:
+    # "Para usuarios LDAP, no se almacena contraseña funcional local."
+    hashed = hash_password(uuid.uuid4().hex)
+    # ↑ Si AUTH_LDAP_ENABLED=false (caso real), el usuario queda con un hash
+    # UUID dummy que ninguna password real puede igualar → 401 perpetuo.
+```
+
+```python
+# MAL — rechaza no-ADMIN sin verificar si LDAP existe siquiera
+if rol != "ADMIN":
+    raise HTTPException(400, "Los usuarios no ADMIN gestionan su contraseña en LDAP")
+    # ↑ Sin LDAP habilitado los usuarios no tienen forma de cambiar password.
+```
+
+**Patrón correcto**:
+
+```python
+# BIEN — siempre verifica el flag antes de asumir el servicio
+if rol == "ADMIN":
+    hashed = hash_password(body.password)
+else:
+    if body.password:
+        hashed = hash_password(body.password)
+    elif not settings.AUTH_LDAP_ENABLED:
+        # Sin LDAP: generar password funcional para que el usuario pueda entrar
+        temp = _generar_temp_password()
+        hashed = hash_password(temp)
+        # devolver `temp` en la respuesta del POST UNA SOLA VEZ
+    else:
+        # LDAP habilitado: dummy OK porque el usuario se autentica fuera
+        hashed = hash_password(uuid.uuid4().hex)
+```
+
+**Detección temprana en code review**: cualquier comentario `"para LDAP"`,
+`"para Redis"`, `"para S3"` debe acompañarse del check del flag correspondiente.
+Si el comentario está solo, es bug latente — el código asume un mundo que el
+deployment puede no tener.
+
+---
+
+## Sanitización PII centralizada en handlers vs refactorear N sitios
+
+Cuando un sistema persiste logs estructurados (audit trails, error logs,
+telemetría) y existen N sitios donde el código emite `logger.error(..., extra={...})`
+con potencial PII en los valores, **siempre preferir sanitización centralizada en
+el handler** sobre refactorear cada sitio individualmente.
+
+**Decisión arquitectónica** (caso OIC v1.5 Slice 2, 2026-06-04):
+
+| Opción | Esfuerzo | Cobertura futura | Mantenimiento |
+|---|---|---|---|
+| Refactorear N sitios uno por uno | O(N) turnos | Solo lo refactorizado | Cada `logger.error` nuevo requiere auditoría |
+| Sanitización centralizada en handler | O(1) turno | Todos los sitios + futuros automáticamente | Cero auditoría manual al agregar nuevos `logger.error` |
+
+**Patrón portable**:
+
+```python
+import re
+
+_PATRON_SENSIBLE = re.compile(
+    r'(password|token|secret|jwt|authorization|cookie|api[_-]?key)([=:])([^&\s"\']+)',
+    re.IGNORECASE,
+)
+
+def sanitizar_url(url: str | None) -> str | None:
+    """Redacta query-params sensibles preservando key y separador."""
+    if not url:
+        return url
+    return _PATRON_SENSIBLE.sub(r"\1\2<redacted>", url)
+
+def sanitizar_valor(valor: Any) -> Any:
+    """Sanitiza recursivamente strings dentro de dict/list/tuple."""
+    if isinstance(valor, str):
+        return _PATRON_SENSIBLE.sub(r"\1\2<redacted>", valor)
+    if isinstance(valor, dict):
+        return {k: sanitizar_valor(v) for k, v in valor.items()}
+    if isinstance(valor, (list, tuple)):
+        return [sanitizar_valor(item) for item in valor]
+    return valor
+```
+
+**Regla del regex**:
+- Grupo 1 (key) y grupo 2 (`=` o `:`) se preservan → mantiene legibilidad
+  (`password=<redacted>` en vez de `<redacted>`).
+- Grupo 3 (valor) se reemplaza por `<redacted>`.
+- Boundary del valor: `&`, whitespace, comilla, paréntesis.
+- `api_key` y `api-key` ambos matchean con `api[_-]?key`.
+
+**Aplicabilidad**: handlers de logging custom, middleware HTTP que redactan headers,
+sanitización de cookies en logs, redactor de stack traces, error reporters
+(Sentry-style). Defensa en profundidad sin tocar el código del caller.
+
+**Limitación documentada**: el regex opera sobre strings; NO sanitiza claves cuyo
+nombre no esté en la lista (no detecta `contraseña` en español, `pwd`, `mot_de_passe`).
+Mantener el regex extensible vía configuración si el proyecto opera en múltiples idiomas.
+
+---
+
+## Generación de tokens y passwords legibles (sin caracteres ambiguos)
+
+Para passwords temporales (reset por admin, primer login, recuperación) que el
+usuario debe transcribir verbalmente o desde papel, usar alfabeto SIN caracteres
+ambiguos: `0` (cero) vs `O` (o mayúscula), `1` (uno) vs `l` (L minúscula) vs `I`
+(i mayúscula).
+
+```python
+import secrets
+
+# 54 chars del alfabeto seguro (sin 0, O, 1, l, I)
+_ALFABETO_LEGIBLE = "abcdefghijkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+
+def generar_password_temporal(longitud: int = 12) -> str:
+    """12 chars → ~71 bits de entropía. Suficiente para temporal que debe
+    cambiarse en primer login. NUNCA persistir en texto plano; el caller
+    la hashea con bcrypt y la devuelve UNA SOLA VEZ en la respuesta del POST."""
+    return "".join(secrets.choice(_ALFABETO_LEGIBLE) for _ in range(longitud))
+```
+
+**NO usar** `secrets.token_urlsafe()` para passwords visibles al humano: incluye
+`-` y `_` que pueden confundir al transcribir. Reservar `token_urlsafe()` para
+tokens de sesión, CSRF, magic links — strings que no se leen ni transcriben.
+
+**Para tokens de uso programático** (API keys, session IDs, refresh tokens):
+`secrets.token_urlsafe(32)` (32 bytes → 256 bits) o `secrets.token_hex(32)`. Sin
+restricción de alfabeto porque el usuario nunca los teclea manualmente.
+
+---
+
 ## Checklist antes de merge a main
 
 - [ ] No hay secrets hardcodeados (revisar con `git grep -i "password\|secret\|token\|key"`)
@@ -149,3 +290,6 @@ vulnerabilidad del OWASP Top 10. Las más frecuentes en este stack:
 - [ ] Sin uso de `eval`, `exec`, `shell=True`
 - [ ] Logs sin datos sensibles
 - [ ] Dependencias nuevas auditadas
+- [ ] Cualquier rama que asuma servicio externo (LDAP/Redis/S3) verifica su flag de config
+- [ ] Sanitización PII centralizada en handlers (no diseminada por N sitios)
+- [ ] Passwords temporales generadas con alfabeto sin chars ambiguos

package/reglas/sin-duplicacion-reglas-globales.md

@@ -96,7 +96,7 @@ node scripts/auditar-claudemd.js
 - **Auditor síncrono**: `scripts/auditar-claudemd.js` (dimensión 7,
   severidad WARN, no bloquea).
 - **Hook async**: `hooks/claudemd-duplicacion-detector.js` (PostToolUse,
-  emite nudge a `.planning/evolucion/nudges.jsonl`).
+  emite nudge a `.planning/evolution/nudges.jsonl`).
 - **Comando**: `/swl:claudemd audit` reporta el conteo; `/swl:claudemd
   refactor` propone el reemplazo concreto.
 

package/scripts/auditar-agentes-gaps.js

@@ -34,7 +34,7 @@ try {
 
 var RAIZ_AGENTES = path.resolve(__dirname, '..', 'agentes');
 var DESTINO_PLANNING = path.resolve(
-  __dirname, '..', '.planning', 'evolucion', 'audit-agentes-gaps.json'
+  __dirname, '..', '.planning', 'evolution', 'audit-agentes-gaps.json'
 );
 
 // Patrones - soportan LF y CRLF (Windows).

package/scripts/auditar-cobertura-frameworks.js

@@ -11,7 +11,7 @@
  * Uso:
  *   node scripts/auditar-cobertura-frameworks.js            # JSON a stdout
  *   node scripts/auditar-cobertura-frameworks.js --resumen  # tabla a stderr
- *   node scripts/auditar-cobertura-frameworks.js --save     # persiste en .planning/evolucion/
+ *   node scripts/auditar-cobertura-frameworks.js --save     # persiste en .planning/evolution/
  *   node scripts/auditar-cobertura-frameworks.js --framework=nist_csf  # solo un framework
  *
  * No falla si un skill no tiene mapeos — solo los skills del dominio de
@@ -35,7 +35,7 @@ try {
 
 const RAIZ_SKILLS = path.resolve(__dirname, '..', 'habilidades');
 const DESTINO = path.resolve(
-  __dirname, '..', '.planning', 'evolucion', 'cobertura-frameworks.json'
+  __dirname, '..', '.planning', 'evolution', 'cobertura-frameworks.json'
 );
 
 const CAMPOS_FRAMEWORK = Object.freeze([

package/scripts/auditar-skills-gaps.js

@@ -10,7 +10,7 @@
  * Uso:
  *   node scripts/auditar-skills-gaps.js             # JSON a stdout
  *   node scripts/auditar-skills-gaps.js --resumen   # solo tabla a stderr
- *   node scripts/auditar-skills-gaps.js --save      # persiste en .planning/evolucion/
+ *   node scripts/auditar-skills-gaps.js --save      # persiste en .planning/evolution/
  *   node scripts/auditar-skills-gaps.js --incluir-excepciones  # incluye gaps excusados en el total
  *
  * Excepciones documentadas: lista inline de skills con gaps justificados por ADR.
@@ -30,7 +30,7 @@ try {
 
 const RAIZ_SKILLS = path.resolve(__dirname, '..', 'habilidades');
 const DESTINO_PLANNING = path.resolve(
-  __dirname, '..', '.planning', 'evolucion', 'audit-skills-gaps.json'
+  __dirname, '..', '.planning', 'evolution', 'audit-skills-gaps.json'
 );
 
 // Patrones de detección

package/scripts/benchmark-memoria.js

@@ -26,7 +26,7 @@
  *   2 - Argumentos inválidos
  *
  * Persistencia opcional: si se setea SWL_BENCHMARK_PERSIST=1, escribe
- * el resultado agregado a `.planning/evolucion/benchmark-memoria.jsonl`
+ * el resultado agregado a `.planning/evolution/benchmark-memoria.jsonl`
  * para tracking histórico.
  */
 
@@ -36,7 +36,7 @@ const path = require('path');
 const { ejecutarDataset } = require('./lib/longmemeval-runner');
 
 const DATASET_DEFAULT = '.planning/benchmark/dataset.jsonl';
-const HISTORICO_PATH  = '.planning/evolucion/benchmark-memoria.jsonl';
+const HISTORICO_PATH  = '.planning/evolution/benchmark-memoria.jsonl';
 
 function uso() {
   console.error('Uso: node scripts/benchmark-memoria.js [--dataset <ruta>] [--limit <n>] [--json] [--verbose]');
@@ -64,7 +64,7 @@ function parseArgs(argv) {
 function persistirHistorico(baseDir, resumen) {
   if (process.env.SWL_BENCHMARK_PERSIST !== '1') return;
   try {
-    const dirEvolucion = path.join(baseDir, '.planning', 'evolucion');
+    const dirEvolucion = path.join(baseDir, '.planning', 'evolution');
     if (!fs.existsSync(dirEvolucion)) fs.mkdirSync(dirEvolucion, { recursive: true });
     const linea = JSON.stringify({
       timestamp: new Date().toISOString(),

package/scripts/generar-inventario.js

@@ -33,7 +33,8 @@ const args = new Set(process.argv.slice(2));
 const DRY  = args.has('--dry-run');
 const SOLO_INV = args.has('--inventario');
 const SOLO_SAL = args.has('--salud');
-const AMBOS = !SOLO_INV && !SOLO_SAL;
+const SOLO_LLMS = args.has('--llms');
+const AMBOS = !SOLO_INV && !SOLO_SAL && !SOLO_LLMS;
 
 // ── Helpers ────────────────────────────────────────────────────────────
 
@@ -427,6 +428,57 @@ function generarSalud() {
   return lines.join('\n');
 }
 
+// ── llms.txt (convención llmstxt.org) ─────────────────────────────────
+// Índice raíz LLM-legible para descubrimiento externo por herramientas/agentes
+// que esperan el estándar. Cifras sincronizadas con INVENTARIO (mismo cómputo)
+// para que el gate de release no detecte drift. Adoptado de obsidian-second-brain
+// (análisis temp/ 2026-06-05); el resto de ese repo era redundante con swl-ses.
+function generarLlmsTxt() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(RAIZ, 'package.json'), 'utf8'));
+  const agentes  = recolectarAgentes().length;
+  const skills   = recolectarSkills().length;
+  const hooks    = recolectarHooks().length;
+  const comandos = contarArchivos(path.join(RAIZ, 'comandos', 'swl'), '.md');
+  const reglasBase = contarArchivos(path.join(RAIZ, 'reglas'), '.md');
+  const reglasLang = fs.readdirSync(path.join(RAIZ, 'reglas', 'lenguajes'))
+    .filter(d => fs.statSync(path.join(RAIZ, 'reglas', 'lenguajes', d)).isDirectory())
+    .reduce((acc, d) => acc + contarArchivos(path.join(RAIZ, 'reglas', 'lenguajes', d), '.md'), 0);
+
+  const L = [];
+  L.push('# swl-ses (@saulwade/swl-ses)');
+  L.push('');
+  L.push(`> Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot (SDLC completo), distribuido como paquete npm y plugin de Claude Code. ${agentes} agentes, ${skills} habilidades, ${comandos} comandos, ${reglasBase} reglas base y ${hooks} hooks. Soporta 11 lenguajes y 7 runtimes (Claude Code, OpenClaude, OpenCode, Gemini, Cursor, Codex, Copilot). Versión ${pkg.version}.`);
+  L.push('');
+  L.push('Archivo generado por `node scripts/generar-inventario.js` — no editar a mano. Las cifras se sincronizan con INVENTARIO.md en cada regeneración.');
+  L.push('');
+  L.push('## Documentación');
+  L.push('');
+  L.push('- [README](README.md): overview público y quickstart');
+  L.push('- [Manual de uso](MANUAL_USO.md): manual operacional completo');
+  L.push('- [Comandos](COMANDOS.md): referencia detallada de cada comando `/swl:*`');
+  L.push('- [Agentes](AGENTS.md): catálogo de agentes con capacidades');
+  L.push('- [Inventario](INVENTARIO.md): conteos oficiales de todos los componentes');
+  L.push('- [Instalación](INSTALACION.md): instalación, perfiles y configuración');
+  L.push('- [Instrucciones del proyecto](CLAUDE.md): convenciones, stack y reglas');
+  L.push('');
+  L.push('## Componentes');
+  L.push('');
+  L.push(`- ${agentes} agentes especializados en \`agentes/\` (orquestación, implementación por stack, revisión, calidad, diseño)`);
+  L.push(`- ${skills} habilidades cargables bajo demanda en \`habilidades/\` (conocimiento operacional con divulgación progresiva)`);
+  L.push(`- ${comandos} comandos \`/swl:*\` en \`comandos/swl/\` (ciclo GSD, calidad, release, diagnóstico)`);
+  L.push(`- ${reglasBase} reglas base + ${reglasLang} reglas por lenguaje en \`reglas/\` (políticas obligatorias por matcher)`);
+  L.push(`- ${hooks} hooks en \`hooks/\` (telemetría, validación, seguridad; zero-deps, escrituras atómicas)`);
+  L.push('');
+  L.push('## Opcional');
+  L.push('');
+  L.push('- [CHANGELOG](CHANGELOG.md): historial de versiones');
+  L.push('- [Índice de ADRs](.planning/adrs/README.md): decisiones de arquitectura');
+  L.push('- [Variables de entorno](docs/variables-entorno.md): configuración opt-in');
+  L.push('');
+
+  return L.join('\n');
+}
+
 // ── Ejecutar ──────────────────────────────────────────────────────────
 
 if (AMBOS || SOLO_INV) {
@@ -450,3 +502,14 @@ if (AMBOS || SOLO_SAL) {
     console.log('SALUD.md generado correctamente.');
   }
 }
+
+if (AMBOS || SOLO_LLMS) {
+  const llms = generarLlmsTxt();
+  if (DRY) {
+    console.log('\n=== llms.txt (dry-run) ===\n');
+    console.log(llms);
+  } else {
+    atomicWriteSync(path.join(RAIZ, 'llms.txt'), llms, 'utf8');
+    console.log('llms.txt generado correctamente.');
+  }
+}

package/scripts/inferir-herramientas-permitidas.js

@@ -14,7 +14,7 @@
  *   node scripts/inferir-herramientas-permitidas.js --dry-run --skill=fastapi-experto
  *   node scripts/inferir-herramientas-permitidas.js --aplicar
  *   node scripts/inferir-herramientas-permitidas.js --aplicar --solo-faltantes
- *   node scripts/inferir-herramientas-permitidas.js --aplicar --log=.planning/evolucion/infer-herramientas.log
+ *   node scripts/inferir-herramientas-permitidas.js --aplicar --log=.planning/evolution/infer-herramientas.log
  *
  * @module scripts/inferir-herramientas-permitidas
  */

package/scripts/instalador.js

@@ -210,10 +210,30 @@ async function install(opciones) {
   // 2b. Filtrar reglas de lenguaje por stack detectado
   // El stack se detecta siempre que: hay reglas de lenguaje en el perfil, O
   // se ejecuta con --force (actualización) para poder limpiar las ya instaladas.
+  // FIX (thrashing de contexto en subagentes): en scope GLOBAL las reglas
+  // por-lenguaje NO se instalan en ~/.claude/rules/. Global no tiene un proyecto
+  // que detectar, así que se instalarían los 8 lenguajes (~69K tokens) y
+  // saturarían la ventana de todo subagente que herede ~/.claude/rules/. Las
+  // reglas por-lenguaje viven project-scoped, donde el stack-filter sí aplica.
+  if (esGlobal) {
+    const antesGlobal = resolucion.archivos.length;
+    resolucion.archivos = resolucion.archivos.filter(
+      a => !(a.rutaRelativa && a.rutaRelativa.startsWith('reglas/lenguajes/'))
+    );
+    const excluidasGlobal = antesGlobal - resolucion.archivos.length;
+    if (excluidasGlobal > 0) {
+      console.log(
+        `\n[stack] Scope global: ${excluidasGlobal} regla(s) por-lenguaje excluidas ` +
+        '(se instalan project-scoped, filtradas por stack; no en ~/.claude/rules/ ' +
+        'para no saturar el contexto de subagentes).'
+      );
+    }
+  }
+
   const tieneReglasLenguaje = resolucion.archivos.some(
     a => a.rutaRelativa && a.rutaRelativa.startsWith('reglas/lenguajes/')
   );
-  const necesitaStack = (tieneReglasLenguaje || force) && !allLangs;
+  const necesitaStack = (tieneReglasLenguaje || force) && !allLangs && !esGlobal;
 
   let stackDetectado = null;
 
@@ -224,7 +244,7 @@ async function install(opciones) {
   // FIX v1.6.6: si el usuario pasa --all-langs pero el perfil actual no incluye
   // reglas/lenguajes/, el flag se ignora silenciosamente. Antes la única pista
   // era el conteo final de archivos. Ahora emitimos warning explícito.
-  if (allLangs && !tieneReglasLenguaje) {
+  if (allLangs && !tieneReglasLenguaje && !esGlobal) {
     console.log(
       '\n[stack] Aviso: --all-langs ignorado — el perfil actual (' +
       (resolucion.perfil || 'core') +
@@ -269,6 +289,16 @@ async function install(opciones) {
     }
   }
 
+  // Scope global: purgar TODAS las reglas por-lenguaje preexistentes de
+  // ~/.claude/rules/ (instalaciones previas dejaban los 8 lenguajes always-loaded,
+  // saturando el contexto de subagentes). Corre en cada install global, no solo --force.
+  if (esGlobal && rutas.reglas) {
+    const purgaGlobal = limpiarReglasSinStack(rutas.reglas, new Set());
+    if (purgaGlobal.eliminados > 0) {
+      console.log(`\n[stack] Scope global: ${purgaGlobal.eliminados} subdir(s) de reglas por-lenguaje purgadas de ~/.claude/rules/ (${purgaGlobal.lenguajes.join(', ')}) — viven project-scoped.`);
+    }
+  }
+
   // 4. Detectar _userland/
   const userlandAgentes = path.join(process.cwd(), '_userland', 'agentes');
   const userlandHabilidades = path.join(process.cwd(), '_userland', 'habilidades');
@@ -416,6 +446,54 @@ async function install(opciones) {
     console.log(`  [migración] ${migracionesAplicadas} archivo(s) de .planning/ migrado(s) de inglés a español`);
   }
 
+  // 6c-bis. Migración de DIRECTORIOS runtime de .planning/ español → inglés.
+  //     Unificación: los paths runtime/técnicos van en inglés (telemetría, perfil,
+  //     logs archivados). NO incluye fases/ (vocabulario GSD de cara al usuario, se
+  //     mantiene español por coherencia con los comandos *-fase). Ver ADR-0031.
+  const MIGRACIONES_DIRS_PLANNING = [
+    { viejo: 'evolucion',      nuevo: 'evolution' },
+    { viejo: 'auto-evolucion', nuevo: 'auto-evolution' },
+    { viejo: 'perfil-usuario', nuevo: 'user-profile' },
+    { viejo: 'archivo',        nuevo: 'archive' },
+  ];
+
+  let dirsMigrados = 0;
+  for (const m of MIGRACIONES_DIRS_PLANNING) {
+    const dirViejo = path.join(process.cwd(), '.planning', m.viejo);
+    const dirNuevo = path.join(process.cwd(), '.planning', m.nuevo);
+
+    if (!fs.existsSync(dirViejo)) continue;
+
+    try {
+      if (!fs.existsSync(dirNuevo)) {
+        // Caso 1: solo existe el viejo → renombrar el directorio completo
+        fs.renameSync(dirViejo, dirNuevo);
+        console.log(`  ✓ Migración dir: .planning/${m.viejo}/ → .planning/${m.nuevo}/`);
+      } else {
+        // Caso 2: ambos existen → mover entradas del viejo al nuevo (sin sobreescribir)
+        let saltadas = 0;
+        for (const entry of fs.readdirSync(dirViejo)) {
+          const src = path.join(dirViejo, entry);
+          const dst = path.join(dirNuevo, entry);
+          if (!fs.existsSync(dst)) fs.renameSync(src, dst);
+          else saltadas++; // conflicto de nombre: se deja en origen (no destructivo)
+        }
+        try { fs.rmdirSync(dirViejo); } catch { /* no vacío: se deja, no destructivo */ }
+        const sufijo = saltadas > 0
+          ? ` (${saltadas} entrada(s) con conflicto dejadas en .planning/${m.viejo}/)`
+          : '';
+        console.log(`  ⊕ Migración dir: .planning/${m.viejo}/ fusionado en .planning/${m.nuevo}/${sufijo}`);
+      }
+      dirsMigrados++;
+    } catch (err) {
+      console.log(`  ! Migración dir ${m.viejo}: ${err.message}`);
+    }
+  }
+
+  if (dirsMigrados > 0) {
+    console.log(`  [migración] ${dirsMigrados} directorio(s) runtime de .planning/ migrado(s) español → inglés`);
+  }
+
   // 6d. Filtrar skills por targets declarados en SKILL.md frontmatter (patrón skillshare)
   //     Si un skill declara targets: [claude, copilot], solo se instala en esos runtimes.
   //     Si no declara targets, se instala en todos (comportamiento por defecto).

package/scripts/lib/dashboard-widgets.js

@@ -122,7 +122,7 @@ const _WIDGET_CATALOG = [
   {
     id: 'nudges-recientes',
     label: 'Nudges Recientes',
-    descripcion: 'Últimos nudges emitidos por hooks de observabilidad (.planning/evolucion/nudges.jsonl)',
+    descripcion: 'Últimos nudges emitidos por hooks de observabilidad (.planning/evolution/nudges.jsonl)',
     categoria: 'evolucion',
     modos: ['offline'],
     tamanoDefault: 'md',
@@ -130,7 +130,7 @@ const _WIDGET_CATALOG = [
   {
     id: 'evoluciones-aplicadas',
     label: 'Evoluciones Aplicadas',
-    descripcion: 'Historial de evoluciones de skills y agentes (.planning/evolucion/evoluciones.jsonl)',
+    descripcion: 'Historial de evoluciones de skills y agentes (.planning/evolution/evoluciones.jsonl)',
     categoria: 'evolucion',
     modos: ['offline'],
     tamanoDefault: 'md',
@@ -138,7 +138,7 @@ const _WIDGET_CATALOG = [
   {
     id: 'alertas-persistentes',
     label: 'Alertas Persistentes',
-    descripcion: 'Alertas activas sin resolver del ciclo AGP (.planning/evolucion/alertas-persistentes.json)',
+    descripcion: 'Alertas activas sin resolver del ciclo AGP (.planning/evolution/alertas-persistentes.json)',
     categoria: 'evolucion',
     modos: ['offline'],
     tamanoDefault: 'md',

package/scripts/lib/drift-detector.js

@@ -17,7 +17,7 @@
  *   - Fuente de datos: JSONL en disco, no SQLite
  *   - Sin dependencias externas (solo Node stdlib: fs, path)
  *   - Métricas configurables via parámetro, no hardcodeadas
- *   - Emite nudge a .planning/evolucion/nudges.jsonl en drift crítico
+ *   - Emite nudge a .planning/evolution/nudges.jsonl en drift crítico
  *
  * @module scripts/lib/drift-detector
  */
@@ -50,7 +50,7 @@ const METRICAS_DEFAULT = [
 
 // Ruta raíz del proyecto (dos niveles arriba de scripts/lib/)
 const RAIZ_PROYECTO = path.resolve(__dirname, '..', '..');
-const RUTA_NUDGES   = path.join(RAIZ_PROYECTO, '.planning', 'evolucion', 'nudges.jsonl');
+const RUTA_NUDGES   = path.join(RAIZ_PROYECTO, '.planning', 'evolution', 'nudges.jsonl');
 
 // ── helpers internos ──────────────────────────────────────────────────────────
 
@@ -202,7 +202,7 @@ function contarNudgesPrevios(metrica, agente) {
 }
 
 /**
- * Emite un nudge a .planning/evolucion/nudges.jsonl cuando se detecta
+ * Emite un nudge a .planning/evolution/nudges.jsonl cuando se detecta
  * drift crítico. Usa fs.appendFileSync (JSONL, no sobreescribe).
  *
  * Aplica repair-loop detection: si el mismo (metrica, agente) ya fue

package/scripts/lib/eval-metrics-store.js

@@ -5,8 +5,8 @@
  *
  * Patrón adoptado de `temp/agentmemory-main/src/eval/metrics-store.ts`.
  * Adaptado a swl-ses: file-based en lugar de SQLite. Persiste:
- *   - JSONL append-only:    `.planning/evolucion/eval-results.jsonl` (cada eval individual)
- *   - JSON agregado:        `.planning/evolucion/eval-metrics.json`  (totales por functionId)
+ *   - JSONL append-only:    `.planning/evolution/eval-results.jsonl` (cada eval individual)
+ *   - JSON agregado:        `.planning/evolution/eval-metrics.json`  (totales por functionId)
  *
  * El JSONL preserva el detalle histórico (un evento por evaluación). El JSON
  * agregado se recalcula incrementalmente: avg latency, avg quality, success
@@ -31,7 +31,7 @@ try {
 
 // ── constantes ────────────────────────────────────────────────────────────────
 
-const DIR_EVOLUCION = path.join('.planning', 'evolucion');
+const DIR_EVOLUCION = path.join('.planning', 'evolution');
 const RUTA_JSONL    = path.join(DIR_EVOLUCION, 'eval-results.jsonl');
 const RUTA_AGREGADO = path.join(DIR_EVOLUCION, 'eval-metrics.json');