sdd-es 2.5.0 → 2.6.0

package/.claude/settings.json

@@ -1,4 +1,28 @@
 {
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node claude-hooks/pre-tool-guard.js"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node claude-hooks/agent-memory.js"
+          }
+        ]
+      }
+    ]
+  },
   "permissions": {
     "allow": [
       "PowerShell(New-Item -ItemType Directory -Path \"C:\\\\Users\\\\usuario\\\\sdd-lite\\\\sdd-lite\\\\tests\" -Force)",

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:claude.com)",
+      "Bash(npm install *)",
+      "Bash(node src/index.js)"
+    ],
+    "additionalDirectories": []
+  }
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,34 @@
+{
+  "name": "sdd-es-marketplace",
+  "owner": {
+    "name": "SDD-ES",
+    "url": "https://github.com/carlos060798/FORGE"
+  },
+  "metadata": {
+    "description": "Marketplace de SDD-ES — Spec-Driven Development en español para Claude Code.",
+    "version": "2.5.0"
+  },
+  "plugins": [
+    {
+      "name": "sdd-es",
+      "source": "./",
+      "description": "Fábrica de software agnóstica al stack: de la idea al despliegue. 14 agentes especializados, mapas estáticos, compresión de tokens, routing inteligente de modelos (Haiku/Sonnet/Opus), memory persistente entre sesiones, observabilidad integrada, técnicas avanzadas de optimización (v2.5.0). Pipeline completo: Idea → IR → Spec → Plan → Tareas → Implementación → Verificación → Deploy.",
+      "version": "2.5.0",
+      "author": {
+        "name": "Danilo Angarita",
+        "email": "daniloangaritagarcia@gmail.com"
+      },
+      "homepage": "https://github.com/carlos060798/FORGE",
+      "license": "MIT",
+      "keywords": [
+        "spec-driven-development",
+        "español",
+        "agentes",
+        "mcp",
+        "agnóstico-al-stack",
+        "tokens-optimization",
+        "memory-persistence"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://claude.ai/schemas/plugin/v1.json",
+  "name": "sdd-es",
+  "version": "2.5.0",
+  "description": "Spec-Driven Development en español. Fábrica de software agnóstica al stack: de la idea al despliegue. Con 14 agentes especializados, mapas, compresión de tokens y técnicas avanzadas de optimización (v2.5.0).",
+  "homepage": "https://github.com/carlos060798/FORGE",
+  "repository": "https://github.com/carlos060798/FORGE",
+  "license": "MIT",
+  "author": {
+    "name": "Danilo Angarita",
+    "email": "daniloangaritagarcia@gmail.com",
+    "url": "https://github.com/carlos060798/FORGE"
+  },
+
+  "userConfig": {
+    "modelo_principal": {
+      "type": "select",
+      "label": "Modelo para agentes de decisión (arquitecto, crítico, seguridad, asesor-datos, revisor)",
+      "options": ["claude-opus-4-8", "claude-sonnet-4-6", "claude-haiku-4-5-20251001"],
+      "default": "claude-opus-4-8"
+    },
+    "perfil_default": {
+      "type": "select",
+      "label": "Perfil de interacción por defecto",
+      "options": ["experto", "guiado"],
+      "default": "experto"
+    },
+    "verbosidad": {
+      "type": "select",
+      "label": "Nivel de detalle en reportes de implementación",
+      "options": ["minimo", "normal", "detallado"],
+      "default": "normal"
+    }
+  },
+
+  "commands": [
+    "sdd",
+    "sdd.constitucion",
+    "sdd.configurar",
+    "sdd.descubrir",
+    "sdd.interpretar",
+    "sdd.diseñar",
+    "sdd.construir",
+    "sdd.exportar",
+    "sdd.compliance",
+    "sdd.especificar",
+    "sdd.importar",
+    "sdd.aclarar",
+    "sdd.checklist",
+    "sdd.planificar",
+    "sdd.tareas",
+    "sdd.analizar",
+    "sdd.implementar",
+    "sdd.qa",
+    "sdd.verificar",
+    "sdd.desplegar",
+    "sdd.canary",
+    "sdd.snapshot",
+    "sdd.retro",
+    "sdd.release",
+    "sdd.glosario",
+    "sdd.estado",
+    "sdd.mapear",
+    "sdd.comprimir",
+    "sdd.optimizar",
+    "sdd.optimizar-memoria",
+    "sdd.adr",
+    "sdd.defect-report",
+    "sdd.ayuda",
+    "sdd.crear-mcp",
+    "sdd.crear-app"
+  ],
+
+  "agents": [
+    "arquitecto",
+    "disenador-api",
+    "asesor-datos",
+    "desarrollador-backend",
+    "desarrollador-frontend",
+    "operaciones",
+    "tester",
+    "revisor",
+    "critico",
+    "seguridad",
+    "investigador",
+    "documentador",
+    "product-designer",
+    "architecture-designer"
+  ],
+
+  "skills": [
+    "deteccion-stack",
+    "gestion-estado",
+    "validacion-spec",
+    "enrutador-agentes",
+    "verificador-implementacion",
+    "indexador",
+    "compresion-tokens",
+    "constitucion-constraint",
+    "modo-guiado",
+    "orquestacion-ptc",
+    "descubrir-idea",
+    "interpretar-idea",
+    "elegir-direccion",
+    "wireframe-mvp",
+    "critica-diseno",
+    "github-connect",
+    "vercel-deploy",
+    "observabilidad-consumo",
+    "effort-router",
+    "memory-compactor",
+    "cache-audit",
+    "token-budget",
+    "adr-indexer",
+    "mutation-detector"
+  ],
+
+  "mcpServers": "./.mcp.json"
+}

package/.gitignore

@@ -0,0 +1,20 @@
+# MCP — dependencias y compilado (no se versionan)
+sdd-lite/mcp-figma/node_modules/
+sdd-lite/mcp-figma/dist/
+
+# Estado local del proyecto (generado en cada repo donde se instala SDD-ES)
+.sdd/
+
+# Variables de entorno
+.env
+.env.local
+
+# Reportes internos de desarrollo (borradores, no documentación de usuario)
+# Se mantienen en disco pero no se publican en el repo.
+REPORTE-ESTADO-PROBLEMAS.md
+RESUMEN-v2.6.0-MVP-COMPLETADO.md
+SPRINT-1-COMPLETADO.md
+CHANGELOG-v2.6.0.md
+
+# Archivos de contenido temporal del sitio de docs (se ensamblan en assets/data.js)
+docs-site/_content-*.js

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    }
+  }
+}

package/README.md

@@ -1,12 +1,16 @@
 # SDD-ES
 
-> **Fábrica de software en español para Claude Code**
-> De la idea al despliegue, agnóstica al stack, con estándares de ingeniería altos.
+> **Una capa de opinión en español sobre las primitivas oficiales de Claude Code**
+> Skills, subagentes, hooks y slash commands orquestados en un flujo idea→deploy, agnóstico al stack.
+>
+> **Para quién:** no-técnicos que quieren construir sin programar (modo guiado) y developers que quieren estándares de ingeniería altos sin boilerplate (modo experto).
 
 [![npm](https://img.shields.io/npm/v/sdd-es)](https://www.npmjs.com/package/sdd-es)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
+📚 **[Documentación completa →](docs-site/)** · sitio navegable bilingüe (ES/EN) con buscador, para no-técnicos y developers. También disponible como Markdown en [`docs/`](docs/README.md).
+
 ---
 
 ## Instalación
@@ -100,7 +104,7 @@ Flujo simplificado (sin jerga técnica):
 
 1. **Describe tu idea:** "Una tienda donde vendo artesanías" (como hablarías con un amigo)
 2. **SDD-ES entiende:** Crea un plan que tú apruebas
-3. **Se construye:** 12 especialistas trabajan en paralelo (sin que hagas nada)
+3. **Se construye:** 14 especialistas trabajan en paralelo (sin que hagas nada)
 4. **Se verifica:** Pruebas automáticas comprueban que todo funciona
 5. **Está en internet:** Tu app está viva en 15-20 minutos
 
@@ -125,7 +129,7 @@ Flujo simplificado (sin jerga técnica):
 
 ---
 
-## Los 26 comandos
+## Los 35 comandos
 
 ### Inicialización
 
@@ -190,7 +194,7 @@ Flujo simplificado (sin jerga técnica):
 
 ---
 
-## Los 12 agentes especializados
+## Los 14 agentes especializados
 
 | Agente | Rol | Modelo recomendado |
 |--------|-----|--------------------|
@@ -206,12 +210,14 @@ Flujo simplificado (sin jerga técnica):
 | `seguridad` | Auditoría de vulnerabilidades | opus |
 | `investigador` | Stack existente, deuda técnica, patrones | sonnet |
 | `documentador` | Documentación técnica útil | sonnet |
+| `product-designer` | Wireframes, UX, validación de diseño | opus |
+| `architecture-designer` | Blueprints técnicos, diagramas de arquitectura | sonnet |
 
 Cambia modelos y activa/desactiva agentes con `/sdd.configurar` o editando `.sdd/sdd.config.yaml`.
 
 ---
 
-## Las 10 skills
+## Las 25 skills
 
 | Skill | Formato | Qué hace |
 |-------|---------|----------|
@@ -224,7 +230,7 @@ Cambia modelos y activa/desactiva agentes con `/sdd.configurar` o editando `.sdd
 | `compresion-tokens` | `.md` | Reglas de compresión estilo caveman para Markdown |
 | `constitucion-constraint` | `.md` | Aplica DEBE/NUNCA de la constitución como hard constraint |
 | `modo-guiado` | `📁 SKILL.md` | Conduce el flujo sin jerga para no-programadores |
-| `orquestacion-ptc` | `📁 SKILL.md` | Patrón PTC: despacha agentes en paralelo, −85% tokens |
+| `orquestacion-ptc` | `📁 SKILL.md` | Patrón PTC: despacha agentes en paralelo, reduce tokens de orquestación |
 
 ---
 
@@ -242,7 +248,7 @@ Cambia modelos y activa/desactiva agentes con `/sdd.configurar` o editando `.sdd
 `/sdd.qa` genera casos E2E desde cada Criterio de Aceptación y los ejecuta en un navegador real vía Playwright MCP — no solo unitarios.
 
 ### Orquestación PTC
-`/sdd.implementar` y `/sdd.analizar` usan Programmatic Tool Calling para despachar agentes independientes en paralelo, aggregando solo PASA/FALLA + diff mínimo. Ahorro esperado: −70 a −85% de tokens en orquestación multi-agente.
+`/sdd.implementar` y `/sdd.analizar` usan Programmatic Tool Calling para despachar agentes independientes en paralelo, agregando solo PASA/FALLA + diff mínimo. El patrón reduce el contexto de orquestación multi-agente al enviar solo resúmenes de resultado en vez del output completo de cada agente.
 
 ### Sprint estructurado
 
@@ -265,9 +271,9 @@ Cada flecha tiene un control. No se construye sin spec; no se publica sin tests
 ```
 tu-proyecto/
 ├── .claude/
-│   ├── commands/sdd.*.md     ← 26 comandos
-│   ├── agents/*.md           ← 12 agentes
-│   ├── skills/               ← 10 skills (flat .md + carpetas SKILL.md)
+│   ├── commands/sdd.*.md     ← 35 comandos
+│   ├── agents/*.md           ← 14 agentes
+│   ├── skills/               ← 25 skills (flat .md + carpetas SKILL.md)
 │   └── hooks/                ← hooks de seguridad pre-instalados
 └── .sdd/
     ├── sdd.config.yaml       ← configuración personalizable
@@ -307,23 +313,24 @@ Todo el plugin es Markdown plano. Personaliza editando archivos:
 
 ## MCP integrado
 
-SDD-ES declara dos servidores MCP en `plugin.json`:
+SDD-ES declara un servidor MCP en `plugin.json`:
 
 | MCP | Cuándo se activa | Para qué |
 |-----|-----------------|----------|
-| `sdd-figma` | Tareas de UI con `figma_file_key` configurado | Extrae diseños de Figma y genera código adaptado al design system local |
 | `navegador` (Playwright) | `/sdd.qa`, palabras clave `e2e`, `prueba` | QA en navegador real sin mantener un navegador propio |
 
 ---
 
-## Ahorro de tokens
+## Reducción de contexto
+
+Las siguientes técnicas reducen el volumen de artefactos que Claude lee por sesión. Los números son estimaciones de bytes de artefactos generados, **no tokens de facturación medidos**.
 
-| Técnica | Ahorro estimado |
-|---------|----------------|
-| Mapas estáticos (`/sdd.mapear`) | −50 a −65k tokens por sesión |
-| Compresión caveman (`/sdd.comprimir`) | −60 a −70% en archivos de memoria |
-| RAG en 3 capas (estado.json → spec activa → constitución) | Carga solo lo necesario por fase |
-| PTC paralelo (`orquestacion-ptc`) | −70 a −85% en orquestación multi-agente |
+| Técnica | Reducción de artefactos |
+|---------|------------------------|
+| Mapas estáticos (`/sdd.mapear`) | Reemplaza indexación completa en cada turno por un índice precalculado |
+| Compresión caveman (`/sdd.comprimir`) | Reduce tamaño de archivos de memoria eliminando redundancias |
+| RAG en 3 capas (estado.json → spec activa → constitución) | Carga solo lo necesario por fase en lugar del proyecto completo |
+| PTC paralelo (`orquestacion-ptc`) | Agrega solo PASA/FALLA por agente en vez de output completo |
 
 ---
 

package/agents/architecture-designer.md

@@ -165,6 +165,43 @@ node -e "
 
 ---
 
+## Skills obligatorios — leer antes de diseñar
+
+```bash
+# CAPA 0 — siempre (~200 tokens)
+cat .sdd/estado.json 2>/dev/null
+cat .sdd/sdd.config.yaml 2>/dev/null | head -30
+
+# CAPA 1 — si hay spec activa (~400 tokens)
+SPEC_ID=$(grep -o '"especificacion_activa": "[^"]*"' .sdd/estado.json 2>/dev/null | cut -d'"' -f4)
+[ -n "$SPEC_ID" ] && cat ".sdd/especificaciones/${SPEC_ID}/spec.md" 2>/dev/null
+
+# CAPA 2 — contexto de producto
+cat .sdd/ir.json 2>/dev/null
+cat .sdd/product-design.json 2>/dev/null
+```
+
+### Habilidades requeridas
+
+- **Simplicity-First Thinking** — la solución más simple que funcione
+- **Tech Stack Knowledge** — conocer opciones reales para cada capa
+- **Trade-off Analysis** — explicar el costo/beneficio de cada decisión
+- **Plain Language Communication** — no usar jerga técnica innecesaria
+
+---
+
+## Lo que NO haces
+
+- ❌ No generas código
+- ❌ No inventas stacks complejos sin justificación
+- ❌ No sugeries microservicios para un MVP (usa monolito)
+- ❌ No obligas a cloud premium (Vercel gratis, Railway gratis, etc. están bien)
+- ❌ No ignoras `tech_preference` del IR — respeita las preferencias del usuario
+- ❌ No usas jerga técnica ("schema relacional con ORM")
+- ❌ No recomiendas más de 5 dependencias principales
+
+---
+
 ## Restricciones
 
 - **No generas código** — solo decides qué stack usar

package/agents/desarrollador-frontend.md

@@ -28,25 +28,18 @@ Implementas UI de producción: componentes, vistas, estado del cliente, navegaci
 - **Componentes pequeños y composables**: <150 líneas, una responsabilidad visual
 - **Performance medible**: no asumes, mides (re-renders, bundle size, latencia)
 
-## Herramienta MCP: sdd-figma-mcp
+## Sistema de diseño local
 
-Si el proyecto tiene Figma conectado (variable `FIGMA_PAT` disponible), usa estas herramientas **antes** de escribir código:
+Antes de escribir cualquier componente UI, lee el sistema de diseño del proyecto:
 
-```
-# Flujo estándar con Figma:
-analizar_sistema_diseño(project_root)   → perfil del sistema de diseño local
-conectar_figma(file_key)                → verifica acceso y metadata del archivo
-listar_componentes(file_key, filter?)   → componentes disponibles en Figma
-traer_componente(file_key, node_id)     → detalle del componente a implementar
-mapear_estilos(file_key, node_id, root) → cruza estilos Figma con tokens locales
-generar_componente(file_key, node_id, root) → genera código adaptado al proyecto
-
-# Si solo quieres mejorar el proyecto sin Figma:
-evaluar_ui_existente(project_root)      → score + problemas + sugerencias
-sugerir_mejoras(project_root)           → lista priorizada de mejoras
+```bash
+# Tokens de diseño (colores, tipografía, espaciado)
+find . -name "tokens.json" -o -name "design-tokens*" -o -name "theme*" 2>/dev/null | head -5
+# Variables CSS o JS de estilos globales
+find . -name "variables.css" -o -name "globals.css" -o -name "tailwind.config*" 2>/dev/null | head -3
 ```
 
-**Regla:** NO generes componentes de Figma sin ejecutar primero `analizar_sistema_diseño` y `mapear_estilos`. El MCP detecta tokens existentes para que el código generado no rompa el sistema de diseño.
+**Regla:** NO generes componentes sin leer primero los tokens y patrones existentes. El código generado debe ser coherente con el sistema de diseño del proyecto.
 
 ## Skills obligatorios — leer antes de implementar
 

package/agents/product-designer.md

@@ -223,6 +223,42 @@ node -e "
 
 ---
 
+## Skills obligatorios — leer antes de diseñar
+
+```bash
+# CAPA 0 — siempre (~200 tokens)
+cat .sdd/estado.json 2>/dev/null
+cat .sdd/sdd.config.yaml 2>/dev/null | head -30
+
+# CAPA 1 — si hay spec activa (~400 tokens)
+SPEC_ID=$(grep -o '"especificacion_activa": "[^"]*"' .sdd/estado.json 2>/dev/null | cut -d'"' -f4)
+[ -n "$SPEC_ID" ] && cat ".sdd/especificaciones/${SPEC_ID}/spec.md" 2>/dev/null
+
+# CAPA 2 — contexto de producto
+cat .sdd/ir.json 2>/dev/null
+```
+
+### Habilidades requeridas
+
+- **Product Thinking** — tomar una necesidad y convertirla en producto
+- **User Empathy** — entender quién usa qué y por qué
+- **Scope Definition** — decir qué entra en V1 y qué no
+- **Design System Usage** — aplicar coherencia visual según DESIGN.md
+
+---
+
+## Lo que NO haces
+
+- ❌ No escribes código ni HTML
+- ❌ No propones arquitectura técnica ni stack
+- ❌ No especificas campos de base de datos ni APIs
+- ❌ No generás wireframes visuales (solo descripciones en JSON)
+- ❌ No tomas decisiones técnicas (p.ej., "usar React" → es rol de `architecture-designer`)
+- ❌ No inventas métricas de producto ("10x más rápido")
+- ❌ No usas jerga técnica al describir pantallas
+
+---
+
 ## Restricciones
 
 - **No generas código HTML** — eso es la skill `wireframe-mvp`

package/claude-hooks/agent-memory.js

@@ -17,7 +17,7 @@
  */
 
 import { createInterface } from "node:readline";
-import { existsSync, mkdirSync, appendFileSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, appendFileSync, statSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 const MEMORIA_UMBRAL_BYTES = 50_000; // 50KB — alerta cuando se supera
@@ -33,6 +33,11 @@ const AGENTES_CON_MEMORIA = new Set([
   "asesor-datos",
   "disenador-api",
   "critico",
+  "desarrollador-backend",
+  "desarrollador-frontend",
+  "tester",
+  "documentador",
+  "operaciones",
 ]);
 
 function detectarAgente() {
@@ -47,6 +52,102 @@ function extraerResumen(contenido) {
   return primera.slice(0, 120).trim();
 }
 
+function extraerADRsDelContenido(contenido) {
+  // Captura comentarios con patrón ADR: {...} en multilenguaje
+  // Soporta: //, /*, #, --, <!-- REM
+  const regex = /(?:\/\/|\/\*|#|--|<!--|REM)\s*ADR:\s*({[^}]*})/g;
+  const adrs = [];
+  let match;
+  while ((match = regex.exec(contenido)) !== null) {
+    try {
+      const json = JSON.parse(match[1]);
+      // Validar campos mínimos
+      if (json.decision && typeof json.decision === "string") {
+        adrs.push(json);
+      }
+    } catch {
+      // Ignorar JSON inválido silenciosamente
+    }
+  }
+  return adrs;
+}
+
+function registrarADRs(cwd, agente, archivo, adrs) {
+  if (adrs.length === 0) return;
+  const adrDir = join(cwd, ".sdd", "arquitectura");
+  const ledgerFile = join(adrDir, "ADRs.jsonl");
+
+  try {
+    if (!existsSync(adrDir)) {
+      mkdirSync(adrDir, { recursive: true });
+    }
+
+    for (const adr of adrs) {
+      const linea = JSON.stringify({
+        ts: new Date().toISOString(),
+        decision: adr.decision,
+        context: adr.context ?? "",
+        alternatives: adr.alternatives ?? [],
+        status: adr.status ?? "accepted",
+        archivo: archivo,
+        agente: agente || "main",
+      });
+      appendFileSync(ledgerFile, linea + "\n", "utf8");
+    }
+
+    if (adrs.length > 0) {
+      process.stderr.write(
+        `📋 [adr-indexer] ${agente}: ${adrs.length} ADR(s) capturado(s) en ${archivo}\n`
+      );
+    }
+  } catch {
+    // Silencioso — nunca interrumpir
+  }
+}
+
+function triggerAutoCompresion(cwd, agente, memoriaFile) {
+  // Extrae entradas duplicadas y deduplica por filepath
+  try {
+    const contenido = readFileSync(memoriaFile, "utf8");
+    const lineas = contenido.split("\n");
+    const header = lineas
+      .slice(0, 6)
+      .join("\n")
+      .concat("\n\n");
+
+    // Regex para extraer entradas: "## YYYY-MM-DD — filepath"
+    const entradas = new Map(); // clave: filepath, valor: {fecha, resumen, linea}
+    const regex = /^## (\d{4}-\d{2}-\d{2}) — (.+?)\n> (.+?)(?=\n##|\n$)/gms;
+    let match;
+    while ((match = regex.exec(contenido)) !== null) {
+      const [, fecha, filepath, resumen] = match;
+      // Guarda solo la entrada más reciente por filepath
+      entradas.set(filepath, { fecha, resumen });
+    }
+
+    // Reconstruye archivo con deduplica
+    let comprimido = header;
+    for (const [filepath, { fecha, resumen }] of entradas) {
+      comprimido += `## ${fecha} — ${filepath}\n> ${resumen}\n\n`;
+    }
+
+    // Backup antes de sobrescribir
+    const backupFile = memoriaFile.replace(".md", ".original.md");
+    writeFileSync(backupFile, contenido, "utf8");
+
+    // Sobrescribe archivo deduplicado
+    writeFileSync(memoriaFile, comprimido, "utf8");
+    const tamanioOriginal = Buffer.byteLength(contenido, "utf8");
+    const tamanioComprimido = Buffer.byteLength(comprimido, "utf8");
+    const ratio = Math.round((tamanioComprimido / tamanioOriginal) * 100);
+    process.stderr.write(
+      `✨ [auto-compress] ${agente}: ${Math.round(tamanioOriginal / 1024)}KB → ${Math.round(tamanioComprimido / 1024)}KB (${ratio}%), backup en .original.md\n`
+    );
+  } catch {
+    // Silencioso — no interrumpir
+  }
+}
+
 function registrarLedger(cwd, agente, toolName, archivoModificado, contenido) {
   const obsDir = join(cwd, ".sdd", "observabilidad");
   const ledgerFile = join(obsDir, "consumo.jsonl");
@@ -95,6 +196,13 @@ function main(raw) {
   // ── Ledger JSONL (aplica a TODOS los agentes) ──────────────────────────────
   registrarLedger(cwd, agente, toolName, archivoModificado, contenido);
 
+  // ── Indexar ADRs (aplica a TODOS los agentes) ──────────────────────────────
+  const adrs = extraerADRsDelContenido(contenido);
+  registrarADRs(cwd, agente, archivoModificado, adrs);
+
+  // ── Registrar mutaciones (aplica a TODOS los agentes) ──────────────────────
+  registrarMutacion(cwd, agente, archivoModificado, toolName);
+
   // ── Memoria persistente (solo agentes del grupo OPUS) ──────────────────────
   if (!agente || !AGENTES_CON_MEMORIA.has(agente)) {
     process.exit(0);
@@ -135,13 +243,15 @@ function main(raw) {
       `🧠 [agent-memory] Registrado en memoria de ${agente}: ${archivoModificado}\n`
     );
 
-    // Alerta de tamaño — no bloquea el flujo, solo informa
+    // Alerta de tamaño + trigger auto-compresión
     try {
       const { size } = statSync(memoriaFile);
       if (size > MEMORIA_UMBRAL_BYTES) {
         process.stderr.write(
-          `⚠️  [agent-memory] Memoria de ${agente} supera ${Math.round(size / 1024)}KB — considera ejecutar /sdd.optimizar memoria\n`
+          `⚠️  [agent-memory] Memoria de ${agente} supera ${Math.round(size / 1024)}KB\n`
         );
+        // Trigger automático de compresión (silencioso, no bloquea)
+        triggerAutoCompresion(cwd, agente, memoriaFile);
       }
     } catch {
       // Silencioso
@@ -152,3 +262,27 @@ function main(raw) {
 
   process.exit(0);
 }
+
+function registrarMutacion(cwd, agente, archivoModificado, toolName) {
+  // Registra cada cambio (mutation) de archivo para tracking de calidad
+  // Permite medir: "¿este archivo fue reescrito 5 veces? ¿problemas de estabilidad?"
+  const mutDir = join(cwd, ".sdd", "observabilidad");
+  const mutFile = join(mutDir, "mutaciones.jsonl");
+
+  try {
+    if (!existsSync(mutDir)) {
+      mkdirSync(mutDir, { recursive: true });
+    }
+
+    const linea = JSON.stringify({
+      ts: new Date().toISOString(),
+      agente: agente || "main",
+      archivo: archivoModificado,
+      tool: toolName,
+      tipo: toolName === "Edit" ? "partial" : "full",
+    });
+    appendFileSync(mutFile, linea + "\n", "utf8");
+  } catch {
+    // Silencioso
+  }
+}