@saulwade/swl-ses 1.3.8 → 1.4.1

package/bin/swl-mcp-server.js

@@ -1,187 +1,187 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * swl-mcp-server — Servidor MCP **EXPERIMENTAL** para exponer la memoria
- * de swl-ses a clientes MCP externos (Cursor, Gemini CLI, OpenCode, etc.).
- *
- * **NO PRODUCCIÓN — STUB EXPERIMENTAL**.
- * Ver `scripts/mcp-server/README.md` para limitaciones detalladas.
- *
- * Modo de transporte: stdio (JSON-RPC sobre stdin/stdout).
- * No HTTP, no auth, no rate limiting.
- *
- * Uso (cliente MCP):
- *   - Configurar el cliente para ejecutar `node /path/to/swl-ses/bin/swl-mcp-server.js`
- *     con stdio.
- *   - Los handlers leen el cwd del proceso para localizar `.planning/`,
- *     `instintos/`, `APRENDIZAJES.md`. Por defecto usa `process.cwd()`.
- *   - Override con env var `SWL_MCP_BASE_DIR` si el cliente arranca el server
- *     desde otro directorio.
- *
- * Protocolo MCP soportado (subset):
- *   - initialize / initialized
- *   - tools/list
- *   - tools/call
- *
- * NO soporta:
- *   - resources/list, prompts/list
- *   - logging, sampling
- *   - cancellation, progress
- *   - HTTP transport
- *
- * Trigger documentado para implementación completa: "uso ≥2 runtimes
- * diferentes (Cursor + Claude Code o similar) consistentemente por
- * ≥1 mes". Hoy: 0 instalaciones reportadas.
- */
-
-const path = require('path');
-
-const { HANDLERS } = require('../scripts/mcp-server/handlers');
-
-const SERVER_NAME = 'swl-mcp-server';
-const SERVER_VERSION = '0.1.0-experimental';
-const PROTOCOL_VERSION = '2024-11-05';
-
-const baseDir = process.env.SWL_MCP_BASE_DIR || process.cwd();
-
-// ── logging ───────────────────────────────────────────────────────────────────
-
-// Stderr para evitar contaminar stdout (que es JSON-RPC).
-function log(level, msg, data) {
-  const linea = JSON.stringify({
-    timestamp: new Date().toISOString(),
-    level,
-    msg,
-    ...(data ? { data } : {}),
-  });
-  process.stderr.write(linea + '\n');
-}
-
-// ── JSON-RPC helpers ──────────────────────────────────────────────────────────
-
-function respuesta(id, result) {
-  return JSON.stringify({ jsonrpc: '2.0', id, result });
-}
-
-function errorResp(id, code, message) {
-  return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
-}
-
-// ── routing ───────────────────────────────────────────────────────────────────
-
-function manejarInitialize(request) {
-  return respuesta(request.id, {
-    protocolVersion: PROTOCOL_VERSION,
-    capabilities: {
-      tools: { listChanged: false },
-    },
-    serverInfo: {
-      name: SERVER_NAME,
-      version: SERVER_VERSION,
-    },
-  });
-}
-
-function manejarToolsList(request) {
-  const tools = Object.entries(HANDLERS).map(([name, def]) => ({
-    name,
-    description: def.description,
-    inputSchema: def.inputSchema,
-  }));
-  return respuesta(request.id, { tools });
-}
-
-function manejarToolsCall(request) {
-  const { name, arguments: args } = request.params || {};
-  const def = HANDLERS[name];
-  if (!def) {
-    return errorResp(request.id, -32601, `Tool no encontrado: ${name}`);
-  }
-  try {
-    const result = def.handler(baseDir, args || {});
-    return respuesta(request.id, {
-      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-    });
-  } catch (err) {
-    log('error', `Excepción en handler ${name}`, { error: err.message });
-    return errorResp(request.id, -32603, `Error interno: ${err.message}`);
-  }
-}
-
-function rutear(request) {
-  switch (request.method) {
-    case 'initialize':
-      return manejarInitialize(request);
-    case 'initialized':
-    case 'notifications/initialized':
-      return null; // notification — sin respuesta
-    case 'tools/list':
-      return manejarToolsList(request);
-    case 'tools/call':
-      return manejarToolsCall(request);
-    case 'ping':
-      return respuesta(request.id, {});
-    default:
-      return errorResp(request.id, -32601, `Método no soportado: ${request.method}`);
-  }
-}
-
-// ── loop principal ────────────────────────────────────────────────────────────
-
-function arrancar() {
-  log('warn', '⚠ swl-mcp-server stub experimental — NO usar en producción');
-  log('info', `Server iniciando`, { name: SERVER_NAME, version: SERVER_VERSION, baseDir });
-
-  let buffer = '';
-
-  process.stdin.setEncoding('utf8');
-  process.stdin.on('data', (chunk) => {
-    buffer += chunk;
-
-    // Cada mensaje JSON-RPC termina con \n
-    let nlIndex;
-    while ((nlIndex = buffer.indexOf('\n')) >= 0) {
-      const linea = buffer.slice(0, nlIndex).trim();
-      buffer = buffer.slice(nlIndex + 1);
-
-      if (!linea) continue;
-
-      let request;
-      try {
-        request = JSON.parse(linea);
-      } catch (err) {
-        log('error', 'JSON inválido recibido', { error: err.message, linea: linea.slice(0, 100) });
-        process.stdout.write(errorResp(null, -32700, 'Parse error') + '\n');
-        continue;
-      }
-
-      const respuestaStr = rutear(request);
-      if (respuestaStr) {
-        process.stdout.write(respuestaStr + '\n');
-      }
-    }
-  });
-
-  process.stdin.on('end', () => {
-    log('info', 'stdin cerrado, server termina');
-    process.exit(0);
-  });
-
-  // Manejo de errores no capturados — nunca crashear silenciosamente
-  process.on('uncaughtException', (err) => {
-    log('error', 'uncaughtException', { error: err.message, stack: err.stack });
-  });
-}
-
-if (require.main === module) {
-  arrancar();
-}
-
-module.exports = {
-  rutear,
-  arrancar,
-  SERVER_NAME,
-  SERVER_VERSION,
-  PROTOCOL_VERSION,
-};
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * swl-mcp-server — Servidor MCP **EXPERIMENTAL** para exponer la memoria
+ * de swl-ses a clientes MCP externos (Cursor, Gemini CLI, OpenCode, etc.).
+ *
+ * **NO PRODUCCIÓN — STUB EXPERIMENTAL**.
+ * Ver `scripts/mcp-server/README.md` para limitaciones detalladas.
+ *
+ * Modo de transporte: stdio (JSON-RPC sobre stdin/stdout).
+ * No HTTP, no auth, no rate limiting.
+ *
+ * Uso (cliente MCP):
+ *   - Configurar el cliente para ejecutar `node /path/to/swl-ses/bin/swl-mcp-server.js`
+ *     con stdio.
+ *   - Los handlers leen el cwd del proceso para localizar `.planning/`,
+ *     `instintos/`, `APRENDIZAJES.md`. Por defecto usa `process.cwd()`.
+ *   - Override con env var `SWL_MCP_BASE_DIR` si el cliente arranca el server
+ *     desde otro directorio.
+ *
+ * Protocolo MCP soportado (subset):
+ *   - initialize / initialized
+ *   - tools/list
+ *   - tools/call
+ *
+ * NO soporta:
+ *   - resources/list, prompts/list
+ *   - logging, sampling
+ *   - cancellation, progress
+ *   - HTTP transport
+ *
+ * Trigger documentado para implementación completa: "uso ≥2 runtimes
+ * diferentes (Cursor + Claude Code o similar) consistentemente por
+ * ≥1 mes". Hoy: 0 instalaciones reportadas.
+ */
+
+const path = require('path');
+
+const { HANDLERS } = require('../scripts/mcp-server/handlers');
+
+const SERVER_NAME = 'swl-mcp-server';
+const SERVER_VERSION = '0.1.0-experimental';
+const PROTOCOL_VERSION = '2024-11-05';
+
+const baseDir = process.env.SWL_MCP_BASE_DIR || process.cwd();
+
+// ── logging ───────────────────────────────────────────────────────────────────
+
+// Stderr para evitar contaminar stdout (que es JSON-RPC).
+function log(level, msg, data) {
+  const linea = JSON.stringify({
+    timestamp: new Date().toISOString(),
+    level,
+    msg,
+    ...(data ? { data } : {}),
+  });
+  process.stderr.write(linea + '\n');
+}
+
+// ── JSON-RPC helpers ──────────────────────────────────────────────────────────
+
+function respuesta(id, result) {
+  return JSON.stringify({ jsonrpc: '2.0', id, result });
+}
+
+function errorResp(id, code, message) {
+  return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+// ── routing ───────────────────────────────────────────────────────────────────
+
+function manejarInitialize(request) {
+  return respuesta(request.id, {
+    protocolVersion: PROTOCOL_VERSION,
+    capabilities: {
+      tools: { listChanged: false },
+    },
+    serverInfo: {
+      name: SERVER_NAME,
+      version: SERVER_VERSION,
+    },
+  });
+}
+
+function manejarToolsList(request) {
+  const tools = Object.entries(HANDLERS).map(([name, def]) => ({
+    name,
+    description: def.description,
+    inputSchema: def.inputSchema,
+  }));
+  return respuesta(request.id, { tools });
+}
+
+function manejarToolsCall(request) {
+  const { name, arguments: args } = request.params || {};
+  const def = HANDLERS[name];
+  if (!def) {
+    return errorResp(request.id, -32601, `Tool no encontrado: ${name}`);
+  }
+  try {
+    const result = def.handler(baseDir, args || {});
+    return respuesta(request.id, {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    });
+  } catch (err) {
+    log('error', `Excepción en handler ${name}`, { error: err.message });
+    return errorResp(request.id, -32603, `Error interno: ${err.message}`);
+  }
+}
+
+function rutear(request) {
+  switch (request.method) {
+    case 'initialize':
+      return manejarInitialize(request);
+    case 'initialized':
+    case 'notifications/initialized':
+      return null; // notification — sin respuesta
+    case 'tools/list':
+      return manejarToolsList(request);
+    case 'tools/call':
+      return manejarToolsCall(request);
+    case 'ping':
+      return respuesta(request.id, {});
+    default:
+      return errorResp(request.id, -32601, `Método no soportado: ${request.method}`);
+  }
+}
+
+// ── loop principal ────────────────────────────────────────────────────────────
+
+function arrancar() {
+  log('warn', '⚠ swl-mcp-server stub experimental — NO usar en producción');
+  log('info', `Server iniciando`, { name: SERVER_NAME, version: SERVER_VERSION, baseDir });
+
+  let buffer = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+
+    // Cada mensaje JSON-RPC termina con \n
+    let nlIndex;
+    while ((nlIndex = buffer.indexOf('\n')) >= 0) {
+      const linea = buffer.slice(0, nlIndex).trim();
+      buffer = buffer.slice(nlIndex + 1);
+
+      if (!linea) continue;
+
+      let request;
+      try {
+        request = JSON.parse(linea);
+      } catch (err) {
+        log('error', 'JSON inválido recibido', { error: err.message, linea: linea.slice(0, 100) });
+        process.stdout.write(errorResp(null, -32700, 'Parse error') + '\n');
+        continue;
+      }
+
+      const respuestaStr = rutear(request);
+      if (respuestaStr) {
+        process.stdout.write(respuestaStr + '\n');
+      }
+    }
+  });
+
+  process.stdin.on('end', () => {
+    log('info', 'stdin cerrado, server termina');
+    process.exit(0);
+  });
+
+  // Manejo de errores no capturados — nunca crashear silenciosamente
+  process.on('uncaughtException', (err) => {
+    log('error', 'uncaughtException', { error: err.message, stack: err.stack });
+  });
+}
+
+if (require.main === module) {
+  arrancar();
+}
+
+module.exports = {
+  rutear,
+  arrancar,
+  SERVER_NAME,
+  SERVER_VERSION,
+  PROTOCOL_VERSION,
+};

package/bin/swl-webhook-server.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * swl-webhook-server — Bootstrap CLI del receptor de webhooks entrantes.
+ *
+ * Lee variables de entorno opt-in, construye las dependencias inyectadas,
+ * arranca el servidor HTTP y maneja shutdown limpio (SIGTERM/SIGINT).
+ *
+ * Activación: requiere SWL_WEBHOOK_LISTEN_PORT. Sin esa variable, el
+ * proceso imprime un mensaje informativo y sale con código 0 (no es
+ * error — sólo opt-in no activado).
+ *
+ * Variables de entorno (ver `docs/variables-entorno.md` § Webhook entrante
+ * para descripción completa):
+ *
+ *   SWL_WEBHOOK_LISTEN_PORT          unset  → no arranca
+ *   SWL_WEBHOOK_LISTEN_HOST          127.0.0.1
+ *   SWL_WEBHOOK_GITHUB_SECRET        unset  → /webhooks/github deshabilitado
+ *   SWL_WEBHOOK_BEARER_SECRET        unset  → /webhooks/generic deshabilitado
+ *   SWL_WEBHOOK_RATE_LIMIT_RPM       60
+ *   SWL_WEBHOOK_ALLOW_IPS            unset (CSV)
+ *   SWL_WEBHOOK_MAX_PAYLOAD_BYTES    1048576 (1 MB)
+ *   SWL_WEBHOOK_INBOX_DIR            .planning/inbox
+ *   SWL_WEBHOOK_LEDGER_PATH          .planning/webhook-events.jsonl
+ *
+ * Uso típico con supervisor (no incluido en SWL — el usuario elige):
+ *
+ *   SWL_WEBHOOK_LISTEN_PORT=8787 SWL_WEBHOOK_GITHUB_SECRET=xxx \
+ *     pm2 start bin/swl-webhook-server.js --name swl-webhook
+ *
+ *   # systemd: ver MANUAL_USO.md § Webhook server.
+ *
+ * @module bin/swl-webhook-server
+ */
+
+const path = require('path');
+const { crearServidor } = require('../gateway/webhook-server');
+const { RateLimiterIP } = require('../hooks/lib/rate-limit-ip');
+const { WebhookDedup } = require('../hooks/lib/webhook-dedup');
+
+const PUERTO_MIN = 1;
+const PUERTO_MAX = 65535;
+const RPM_DEFAULT = 60;
+const MAX_PAYLOAD_DEFAULT = 1024 * 1024;
+const HOST_DEFAULT = '127.0.0.1';
+const INBOX_DIR_DEFAULT = path.join('.planning', 'inbox');
+const LEDGER_PATH_DEFAULT = path.join('.planning', 'webhook-events.jsonl');
+
+/**
+ * Construye el objeto de configuración + deps desde variables de entorno.
+ *
+ * Separado del main() para testear sin tocar process.env real.
+ *
+ * @param {object} env Objeto con las variables (típicamente process.env).
+ * @returns {{configurado: boolean, errores: string[], config: object|null, deps: object|null}}
+ */
+function construirDepsDesdeEnv(env) {
+  const errores = [];
+
+  // Opt-in: sin LISTEN_PORT, no se arranca nada
+  if (!env.SWL_WEBHOOK_LISTEN_PORT) {
+    return { configurado: false, errores: [], config: null, deps: null };
+  }
+
+  const port = Number.parseInt(env.SWL_WEBHOOK_LISTEN_PORT, 10);
+  if (!Number.isInteger(port) || port < PUERTO_MIN || port > PUERTO_MAX) {
+    errores.push(`SWL_WEBHOOK_LISTEN_PORT inválido: "${env.SWL_WEBHOOK_LISTEN_PORT}" (debe ser entero ${PUERTO_MIN}-${PUERTO_MAX})`);
+  }
+
+  const host = env.SWL_WEBHOOK_LISTEN_HOST || HOST_DEFAULT;
+
+  const githubSecret = env.SWL_WEBHOOK_GITHUB_SECRET || null;
+  const bearerSecret = env.SWL_WEBHOOK_BEARER_SECRET || null;
+
+  if (!githubSecret && !bearerSecret) {
+    errores.push('Ningún endpoint configurado: definir SWL_WEBHOOK_GITHUB_SECRET o SWL_WEBHOOK_BEARER_SECRET (o ambos).');
+  }
+
+  const rpm = parseEntero(env.SWL_WEBHOOK_RATE_LIMIT_RPM, RPM_DEFAULT);
+  if (rpm <= 0) {
+    errores.push(`SWL_WEBHOOK_RATE_LIMIT_RPM inválido: "${env.SWL_WEBHOOK_RATE_LIMIT_RPM}" (debe ser entero > 0)`);
+  }
+
+  const maxPayloadBytes = parseEntero(env.SWL_WEBHOOK_MAX_PAYLOAD_BYTES, MAX_PAYLOAD_DEFAULT);
+  if (maxPayloadBytes <= 0) {
+    errores.push(`SWL_WEBHOOK_MAX_PAYLOAD_BYTES inválido: "${env.SWL_WEBHOOK_MAX_PAYLOAD_BYTES}" (debe ser entero > 0)`);
+  }
+
+  const allowIps = parseCsv(env.SWL_WEBHOOK_ALLOW_IPS);
+
+  const inboxDir = env.SWL_WEBHOOK_INBOX_DIR || INBOX_DIR_DEFAULT;
+  const ledgerPath = env.SWL_WEBHOOK_LEDGER_PATH || LEDGER_PATH_DEFAULT;
+
+  if (errores.length > 0) {
+    return { configurado: true, errores, config: null, deps: null };
+  }
+
+  const config = { port, host, githubSecret, bearerSecret, rpm, maxPayloadBytes, allowIps, inboxDir, ledgerPath };
+  const deps = {
+    inboxDir,
+    dedup: new WebhookDedup({ rutaLedger: ledgerPath }),
+    rateLimiter: new RateLimiterIP({ rpm }),
+    githubSecret,
+    bearerSecret,
+    maxPayloadBytes,
+    allowIps,
+  };
+
+  return { configurado: true, errores: [], config, deps };
+}
+
+function parseEntero(raw, defecto) {
+  if (raw === undefined || raw === null || raw === '') return defecto;
+  const n = Number.parseInt(raw, 10);
+  return Number.isInteger(n) ? n : -1;  // -1 = inválido (la validación lo captura)
+}
+
+function parseCsv(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+  const items = raw.split(',').map(s => s.trim()).filter(Boolean);
+  return items.length > 0 ? items : null;
+}
+
+/**
+ * Punto de entrada del CLI. Llamado sólo cuando este archivo se ejecuta
+ * directamente (no en require/import).
+ */
+function main() {
+  const { configurado, errores, config, deps } = construirDepsDesdeEnv(process.env);
+
+  if (!configurado) {
+    console.error('SWL_WEBHOOK_LISTEN_PORT no está definido. El webhook server no se arranca.');
+    console.error('Para activar, definir las variables opt-in. Ver docs/variables-entorno.md § Webhook entrante.');
+    process.exit(0);
+  }
+
+  if (errores.length > 0) {
+    for (const err of errores) console.error(`[error] ${err}`);
+    process.exit(1);
+  }
+
+  const server = crearServidor(deps);
+
+  server.on('error', err => {
+    console.error(JSON.stringify({ nivel: 'error', msg: 'server-error', err: err.message }));
+    process.exit(1);
+  });
+
+  server.listen(config.port, config.host, () => {
+    const addr = server.address();
+    const endpoints = [];
+    if (config.githubSecret) endpoints.push('/webhooks/github');
+    if (config.bearerSecret) endpoints.push('/webhooks/generic');
+    endpoints.push('/healthz');
+
+    console.log(JSON.stringify({
+      nivel: 'info',
+      msg: 'webhook-server-started',
+      bind: `${addr.address}:${addr.port}`,
+      endpoints,
+      inboxDir: config.inboxDir,
+      ledgerPath: config.ledgerPath,
+      rpm: config.rpm,
+      maxPayloadBytes: config.maxPayloadBytes,
+      allowIpsCount: config.allowIps ? config.allowIps.length : 0,
+      ts: new Date().toISOString(),
+    }));
+  });
+
+  const shutdown = (sig) => {
+    console.log(JSON.stringify({ nivel: 'info', msg: 'shutdown', sig, ts: new Date().toISOString() }));
+    server.close(() => process.exit(0));
+    // Forzar salida si el server tarda demasiado en cerrar conexiones
+    setTimeout(() => process.exit(1), 10000).unref();
+  };
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+}
+
+// Sólo arrancar si se invoca directamente (no en require)
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  construirDepsDesdeEnv,
+  // Para tests
+  _defaults: {
+    PUERTO_MIN,
+    PUERTO_MAX,
+    RPM_DEFAULT,
+    MAX_PAYLOAD_DEFAULT,
+    HOST_DEFAULT,
+    INBOX_DIR_DEFAULT,
+    LEDGER_PATH_DEFAULT,
+  },
+};

package/comandos/swl/.evolved.json

@@ -1,23 +1,23 @@
-{
-  "release.md": {
-    "evolved": true,
-    "evolvedFrom": "5.4.0",
-    "evolvedAt": "2026-04-11",
-    "evolvedBy": "aprender",
-    "evolvedNote": "mejora de metodología: checklist obligatoria de archivos de versión en paso 6"
-  },
-  "aprender.md": {
-    "evolved": true,
-    "evolvedFrom": "5.12.3",
-    "evolvedAt": "2026-04-25",
-    "evolvedBy": "aprender",
-    "evolvedNote": "Paso 2 — filtro crítico obligatorio sobre reportes de sub-agentes Explore para evitar sobre-ingeniería al analizar papers académicos"
-  },
-  "verificar.md": {
-    "evolved": true,
-    "evolvedFrom": "5.12.3",
-    "evolvedAt": "2026-04-26",
-    "evolvedBy": "evolucionar",
-    "evolvedNote": "flag --until-converge para iterar verificar→corregir→re-verificar hasta 0 hallazgos CRÍTICO+ALTO+MAYOR (max-iter=5, --no-prompt CI, detección adversarial ≥5 hallazgos nuevos)"
-  }
+{
+  "release.md": {
+    "evolved": true,
+    "evolvedFrom": "5.4.0",
+    "evolvedAt": "2026-04-11",
+    "evolvedBy": "aprender",
+    "evolvedNote": "mejora de metodología: checklist obligatoria de archivos de versión en paso 6"
+  },
+  "aprender.md": {
+    "evolved": true,
+    "evolvedFrom": "5.12.3",
+    "evolvedAt": "2026-04-25",
+    "evolvedBy": "aprender",
+    "evolvedNote": "Paso 2 — filtro crítico obligatorio sobre reportes de sub-agentes Explore para evitar sobre-ingeniería al analizar papers académicos"
+  },
+  "verificar.md": {
+    "evolved": true,
+    "evolvedFrom": "5.12.3",
+    "evolvedAt": "2026-04-26",
+    "evolvedBy": "evolucionar",
+    "evolvedNote": "flag --until-converge para iterar verificar→corregir→re-verificar hasta 0 hallazgos CRÍTICO+ALTO+MAYOR (max-iter=5, --no-prompt CI, detección adversarial ≥5 hallazgos nuevos)"
+  }
 }

package/comandos/swl/adoptar-proyecto.md

@@ -168,7 +168,26 @@ Si `/swl:mapear-codebase` ya lo generó (opción B), solo verificar. Si no:
 - Dependencias con CVEs conocidos (si `pip-audit` o `npm audit` están disponibles)
 - Archivos con más de 500 líneas
 
-## Paso 8 — Reporte final
+## Paso 8 — Verificar/actualizar CLAUDE.md del proyecto
+
+Verificar el estado de `CLAUDE.md` en la raíz del proyecto:
+
+- **Si NO existe**: generarlo con la estructura mínima de `/swl:claudemd init-project`.
+  **OBLIGATORIO** incluir como primera sección bajo el título:
+  ```markdown
+  ## Reglas obligatorias
+
+  @reglas/usar-sistema-swl.md
+  ```
+- **Si existe pero NO incluye `@reglas/usar-sistema-swl.md`**: agregar la
+  referencia en una sección "Reglas obligatorias" cerca del inicio del
+  archivo, preservando el contenido existente.
+- **Si existe e incluye la referencia**: no tocar.
+
+Esta referencia carga la matriz operacional del sistema SWL al inicio de cada
+sesión y es el contrato base de uso del sistema para el proyecto adoptado.
+
+## Paso 9 — Reporte final
 
 ```
 === Proyecto adoptado exitosamente ===
@@ -183,6 +202,7 @@ Archivos generados:
   ✓ .planning/research/FUNCIONALIDADES.md — inventario de funcionalidades
   ✓ .planning/research/RESUMEN.md       — resumen ejecutivo consolidado
   ✓ .planning/research/TRAMPAS.md       — deuda técnica y anti-patrones
+  ✓ CLAUDE.md                          — creado o actualizado con @reglas/usar-sistema-swl.md
 
 Hallazgos clave:
   1. [hallazgo más importante]