PROJECT_DEVLOG.md

# PROJECT_DEVLOG.md — DotForge IDE

Bitácora viva de desarrollo. Se actualiza **en cada iteración** del bucle de trabajo.

- **Proyecto:** DotForge IDE — distribución de IDE para C# / .NET 9+ / Blazor
- **Inicio:** 2026-08-23
- **Estado global:** 🟢 v2.8.0 — 27 fases cerradas, 387/388 hitos. El único pendiente (F5.7, artefactos de macOS) está bloqueado por plataforma y documentado en la Fase 5.

Leyenda: `[ ]` pendiente · `[~]` en curso · `[x]` completado y **verificado con un comando**

---

## Entorno detectado (2026-08-23)

| Herramienta | Versión |
|---|---|
| Node.js | v24.19.0 |
| npm | 11.17.0 |
| .NET SDK | 10.0.400 |
| .NET Runtime | 10.0.11 (no hay runtime 9.0 instalado) |
| Git | 2.55.0.windows.3 |
| Python | 3.12.10 |
| SO | Windows 11 Pro 10.0.26200 |
| CPU | 12 núcleos |
| Red | NuGet / npm / GitHub accesibles (HTTP 200) |

**Implicación:** las plantillas targetean `net9.0` (build OK vía targeting pack de NuGet), pero
`dotnet run` de un `net9.0` fallaría en esta máquina por falta de runtime 9.0. La suite de tests
por tanto **compila** pero no **ejecuta** los proyectos generados. Se añade el flag
`--framework net10.0` para quien tenga el runtime alineado.

---

## Roadmap por fases

### Fase 0 — Setup y documentación
- [x] F0.1 Crear `CLAUDE.md` (comandos, layout, convenciones, trampas del entorno)
- [x] F0.2 Crear `AGENTS.md` (10 sub-agentes con rol, prompt y criterio de aceptación)
- [x] F0.3 Crear `PROJECT_DEVLOG.md` con checklist por fases
- [x] F0.4 Estructura de directorios del repositorio
- [x] F0.5 `package.json`, `tsconfig.json`, `.gitignore`, `.editorconfig`
- [x] F0.6 Materializar los sub-agentes en `.claude/agents/`
- [x] F0.7 `npm install` verde

### Fase 1 — ★ Módulo de Scaffolding (generador de arquitecturas)
- [x] F1.1 Motor de plantillas (`engine.ts`): tokens, condicionales, filtros de nombre
- [x] F1.2 Modelo de blueprint + registro de arquitecturas
- [x] F1.3 Generador: resolución de rutas, escritura, `.sln`, post-proceso
- [x] F1.4 Blueprint **Clean Architecture** (Domain / Application / Infrastructure / UI)
- [x] F1.5 Blueprint **Hexagonal** (Domain / Ports / Adapters)
- [x] F1.6 Blueprint **DDD + CQRS** (Agregados, VOs, Eventos, Dispatcher, Repos)
- [x] F1.7 CRUD de ejemplo funcional en cada blueprint (entidad real + endpoints)
- [x] F1.8 UI Blazor de ejemplo (listado + alta) enlazada al backend
- [x] F1.9 `appsettings.json`, Serilog, OpenAPI/Scalar, EF Core preconfigurados
- [x] F1.10 Proyecto de tests xUnit generado por plantilla
- [x] F1.11 CLI `dotforge` headless (`list`, `new`, flags, `--json`)
- [x] F1.12 Tests: `dotnet build` real de las 3 arquitecturas

### Fase 2 — LSP / IntelliSense C#
- [x] F2.1 Adquisición de `Microsoft.CodeAnalysis.LanguageServer` desde feed `dotnet-tools`
- [x] F2.2 Fallback a OmniSharp-Roslyn
- [x] F2.3 Transporte stdio con framing `Content-Length`
- [x] F2.4 Handshake `initialize` / `initialized` + capacidades
- [x] F2.5 Puente IPC main ↔ renderer para tráfico LSP
- [x] F2.6 Adaptadores Monaco: completion, hover, signature help, definition, references
- [x] F2.7 Diagnósticos en el editor y en el panel de problemas
- [x] F2.8 Formateo y code actions
- [x] F2.9 Indicador de estado del LSP en la barra inferior

### Fase 3 — UI, branding y lenguajes
- [x] F3.1 Shell de la aplicación (activity bar, sidebar, tabs, panel, status bar)
- [x] F3.2 Tema **DotForge Purple** (oscuro) + variante clara
- [x] F3.3 Integración de Monaco con carga local del vendor
- [x] F3.4 Gramática Razor/Blazor (Monarch) + snippets
- [x] F3.5 Auto-cierre y auto-renombrado de etiquetas Razor
- [x] F3.6 Explorador visual de soluciones `.sln` / `.csproj`
- [x] F3.7 Panel visual de NuGet (buscar, instalar, actualizar, desinstalar)
- [x] F3.8 Terminal integrada
- [x] F3.9 Panel de problemas y de salida
- [x] F3.10 Wizard visual del generador de arquitecturas
- [x] F3.11 Paleta de comandos + atajos Win/macOS
- [x] F3.12 Pantalla de bienvenida con branding

### Fase 4 — Toolchain .NET y depuración
- [x] F4.1 Parser de `.sln` (clásico) y `.slnx`
- [x] F4.2 Parser de `.csproj` SDK-style
- [x] F4.3 Runner de tareas (`build`, `run`, `test`, `clean`, `restore`)
- [x] F4.4 Parseo de la salida de MSBuild a diagnósticos
- [x] F4.5 Hot Reload con `dotnet watch`
- [x] F4.6 Adquisición de NetCoreDbg (win-x64, osx-x64, osx-arm64)
- [x] F4.7 Bridge DAP: breakpoints, stepping, variables, call stack
- [x] F4.8 Registro de procesos hijo y apagado limpio

### Fase 5 — Build multiplataforma y empaquetado
- [x] F5.1 `scripts/build.mjs` con esbuild (main, preload, renderer, cli)
- [x] F5.2 Copia del vendor de Monaco
- [x] F5.3 Generador de iconos `.ico` / `.icns` / `.png` sin herramientas nativas
- [x] F5.4 `electron-builder.yml`: NSIS, portable zip, dmg, zip macOS (arm64 + x64)
- [x] F5.5 `npm run pack` (smoke test desempaquetado)
- [x] F5.6 `npm run dist:win` → artefactos reales en `/dist`
- [ ] F5.7 `npm run dist:mac` → artefactos reales en `/dist` — **bloqueado por plataforma**:
      electron-builder no puede generar `.dmg` desde Windows. Resuelto con `scripts/dist-mac.mjs`
      (mensaje accionable + salida con código 2) y con `.github/workflows/release.yml`, que lo
      construye en un runner `macos-latest`. Se completa al ejecutarse en macOS o en CI.
- [x] F5.8 `scripts/verify-dist.mjs` valida el contenido de `/dist`

### Fase 6 — QA, cierre y documentación final
- [x] F6.1 Suite de tests unitarios del motor de plantillas
- [x] F6.2 Tests de contract IPC
- [x] F6.3 Tests de seguridad (path traversal, superficie del preload)
- [x] F6.4 Test de humo de arranque de Electron
- [x] F6.5 `npm test` verde de punta a punta
- [x] F6.6 `README.md` final
- [x] F6.7 Revisión final de `CLAUDE.md`, `AGENTS.md`, `PROJECT_DEVLOG.md`

### Fase 7 — Rediseño de UI/UX
- [x] F7.1 Sistema de iconos vectoriales propio (61 piezas, rejilla 24×24, trazo 1.75)
- [x] F7.2 Galería de iconos como modo de diagnóstico (`--icons`) para revisarlos a ojo
- [x] F7.3 Paleta suave estilo Slate/Tokyo Night, sin negros puros ni blancos brillantes
- [x] F7.4 Variante clara completa con contraste AA
- [x] F7.5 Escala tipográfica y de espaciado en tokens (`--text-*`, `--leading-*`)
- [x] F7.6 Resintonizado de la sintaxis C#/Razor a un rango de saturación estrecho
- [x] F7.7 Explorador: jerarquía real solución → carpetas → proyectos → archivos
- [x] F7.8 Anidamiento inteligente de archivos (`.razor.cs`, `.razor.css`, `appsettings.*.json`, …)
- [x] F7.9 Guías de sangría con resalte del nivel activo
- [x] F7.10 Insignias de tipo de proyecto (Blazor, Web API, Lib, Tests, RCL, CLI, Job, WASM)
- [x] F7.11 Detección del tipo de proyecto en el proceso principal (SDK + contenido)
- [x] F7.12 Iconos por carpeta con significado (Controllers, Models, Services, Pages, …)
- [x] F7.13 Filtro de archivos en el explorador y "contraer todo"
- [x] F7.14 Menú contextual de proyecto con iconos y reposicionamiento dentro de la ventana
- [x] F7.15 Barra de actividad reducida a 5 herramientas + ajustes
- [x] F7.16 Barra de estado simplificada: SDK, LSP, rama de Git, problemas
- [x] F7.17 Servicio de estado de Git (rama y archivos sucios) con caché
- [x] F7.18 Panel de ajustes en la barra lateral
- [x] F7.19 Asistente de arquitecturas con tarjetas, iconos y diagrama de capas
- [x] F7.20 Iconos en pestañas del editor, panel, paleta y bienvenida
- [x] F7.21 Modos de diagnóstico `--ui=` y `--probe=` para revisar la interfaz sin ganchos en producción
- [x] F7.22 Pruebas de las reglas visuales (anidamiento, iconos, insignias, geometría SVG)
- [x] F7.23 Compilación de prueba del rediseño: artefactos Windows, verificación y arranque real

### Fase 8 — Documentación didáctica en las soluciones generadas
- [x] F8.1 Plantilla `README.md.tmpl` propia por arquitectura (clean, hexagonal, ddd)
- [x] F8.2 Introducción a la arquitectura + diagramas **Mermaid** (dependencias y flujo de una petición)
- [x] F8.3 Mapa de carpetas proyecto a proyecto con tabla "DEBE / TIENE PROHIBIDO" por capa
- [x] F8.4 Matriz de la regla de dependencia y dependencias permitidas de cada proyecto
- [x] F8.5 Guía paso a paso "cómo añadir una funcionalidad" con código real de la arquitectura
- [x] F8.6 Explicación del CRUD de ejemplo incluido, archivo por archivo
- [x] F8.7 Sección de comandos: `restore`, `build`, `test`, `run`, `watch`, `ef`, NuGet, URLs y puertos
- [x] F8.8 Antipatrones frecuentes por arquitectura y cómo evitarlos
- [x] F8.9 Contenido condicionado a las opciones del wizard (UI, base de datos, pruebas, framework)
- [x] F8.10 Aviso del README en el resultado del wizard y en la salida de la CLI
- [x] F8.11 Pruebas: estructura de las plantillas (`tests/unit`) y READMEs generados (`tests/scaffold`)

### Fase 9 — Selector de inicio y terminal asistida
- [x] F9.1 Modelo puro de perfiles de inicio (`src/shared/startup.ts`): proyectos ejecutables, perfiles, modos
- [x] F9.2 Persistencia por workspace en `userData/startup-profiles.json`
- [x] F9.3 Selector en la barra superior: desplegable de proyecto/perfil, conmutador de modo y Play/Stop
- [x] F9.4 Modal multiproyecto: casillas, orden de arranque, guardar y editar perfiles con nombre
- [x] F9.5 Orquestación del arranque del perfil activo (depuración o sin depurar con Hot Reload)
- [x] F9.6 Un canal de salida por proceso, con nombre de proyecto, estado y puerto detectado
- [x] F9.7 Motor de sugerencias de la terminal (`src/renderer/terminal-suggest.ts`)
- [x] F9.8 Sugerencias de git con ramas reales del repositorio (`git:branches`)
- [x] F9.9 Sugerencias de la CLI de .NET, incluidos compuestos y paquetes NuGet habituales
- [x] F9.10 Texto fantasma en línea y menú, aceptables con Tab o flecha derecha
- [x] F9.11 Modos de diagnóstico `--ui=startup`, `--ui=startup-dialog`, `--ui=terminal-suggest`
- [x] F9.12 Pruebas: 22 del modelo de perfiles y 38 del motor de sugerencias

### Fase 10 — ★ DotForge AI Assistant
- [x] F10.1 Modelo compartido del asistente (`src/shared/ai.ts`): proveedores, catálogo de modelos y preferencias
- [x] F10.2 Servicio de IA en el proceso principal (`src/main/services/ai/`) con streaming y cancelación
- [x] F10.3 Tres proveedores: Anthropic, OpenAI y local (Ollama), con endpoint configurable
- [x] F10.4 Almacén de claves cifrado con `safeStorage` (DPAPI / Keychain), sin caída a texto plano
- [x] F10.5 Contratos IPC `ai:status`, `ai:set-key`, `ai:probe`, `ai:send`, `ai:cancel` y eventos de streaming
- [x] F10.6 Sexto icono en la barra de actividad y panel de chat con respuesta token a token
- [x] F10.7 Inyección de contexto RAG: archivo activo, selección, arquitectura y diagnósticos de compilación
- [x] F10.8 Reglas de arquitectura por proyecto (Clean, Hexagonal, DDD) impuestas desde el proceso principal
- [x] F10.9 Asistente en línea `Ctrl+I` / `Cmd+I` con vista previa de diferencias y aceptar/descartar
- [x] F10.10 Acciones rápidas en el menú contextual del editor y del árbol de archivos
- [x] F10.11 Sección "Asistente de IA" en los ajustes, con "Probar conexión" y control del contexto enviado
- [x] F10.12 Modo de diagnóstico `--ui=ai` y menú nativo "IA"
- [x] F10.13 Pruebas: 113 nuevas (proveedores, contexto RAG, diferencias y streaming de punta a punta)

### Fase 11 — Control de fuentes, procesos visibles y logs de .NET
- [x] F11.1 Modelo puro del control de fuentes (`src/shared/git.ts`): parseo de `git status --porcelain --branch`
- [x] F11.2 Servicio de git en el proceso principal: preparar, quitar, descartar, commit, push, pull, sync, ramas
- [x] F11.3 Contratos IPC `git:repository`, `git:stage`, `git:unstage`, `git:discard`, `git:commit`,
      `git:push`, `git:pull`, `git:sync`, `git:checkout`, `git:create-branch`, `git:file-diff`
- [x] F11.4 Icono dedicado en la barra de actividad, con insignia del número de archivos con cambios
- [x] F11.5 Panel con secciones colapsables "Cambios preparados" y "Cambios", letras M/A/D/U y acciones al pasar el ratón
- [x] F11.6 Editor de diferencias lado a lado de Monaco, con pestaña propia y modelos `dotforge-diff:`
- [x] F11.7 Caja de mensaje multilínea con `Ctrl+Enter` / `Cmd+Enter` y enmienda del último commit
- [x] F11.8 Botones Commit / Push / Pull / Sync con indicador de adelanto y retraso
- [x] F11.9 Selector de rama en la cabecera, con creación de rama (`git checkout -b`)
- [x] F11.10 Pastillas de estado por proceso en la barra superior, con puerto y color de estado
- [x] F11.11 Clic en una pastilla enfoca el canal de salida de ese proceso
- [x] F11.12 Cabecera de canal: nombre, insignia de tipo, estado, enlace HTTPS y reinicio/parada individuales
- [x] F11.13 Ajuste "Nivel de salida de .NET CLI" (Minimal / Normal / Detailed / Diagnostic)
- [x] F11.14 Inyección de la verbosidad en `build`, `run`, `watch`, `test`, `clean`, `restore` y `format`
- [x] F11.15 Entorno extendido en niveles altos: registro de ASP.NET Core, errores detallados y traza del host
- [x] F11.16 El interruptor del asistente de IA atenúa su icono, bloquea la navegación y explica dónde encenderlo
- [x] F11.17 Modos de diagnóstico `--ui=git`, `--ui=git-diff`, `--ui=startup-play`, `--ui=ai-toggle`, `--wait=`, `--ui-wait=`
- [x] F11.18 Pruebas: 98 nuevas (parseo de git, diff de Monaco, verbosidad, conmutador de IA y servicio de git real)

### Fase 12 — Gestor de EF Core y cliente HTTP integrado
- [x] F12.1 Modelo puro de EF Core (`src/shared/efcore.ts`): bloque JSON de la CLI, migraciones, contextos y argumentos
- [x] F12.2 Esquema deducido de las migraciones (`src/shared/efcore-schema.ts`): tablas, columnas, claves e índices
- [x] F12.3 Cadenas de conexión de los `appsettings*.json`, con proveedor detectado y contraseña tapada
- [x] F12.4 Servicio `efcore-service.ts`: lectura con `execFile` y escritura transmitida por el canal de tareas
- [x] F12.5 Contratos IPC `efcore:migrations`, `efcore:contexts`, `efcore:run`, `efcore:schema`, `efcore:connections`
- [x] F12.6 Quinto icono de la barra de actividad y panel "Base de datos" con tres secciones colapsables
- [x] F12.7 Añadir migración, actualizar base de datos y quitar la última, con confirmación si ya está aplicada
- [x] F12.8 Modelo puro del formato `.http` / `.rest` (`src/shared/http-file.ts`): bloques, variables y resolución
- [x] F12.9 Gramática Monarch del lenguaje `http` y su registro en Monaco
- [x] F12.10 Lente de código "Enviar petición" sobre cada bloque de un archivo `.http`
- [x] F12.11 Cliente HTTP en el proceso principal (`http-client-service.ts`) con redirecciones y tiempos
- [x] F12.12 Pestaña "HTTP" del panel inferior: estado, tiempo, tamaño, cuerpo, cabeceras e historial
- [x] F12.13 Detección de endpoints Minimal API y de controladores (`src/shared/api-endpoints.ts`)
- [x] F12.14 Lente "Probar «verbo ruta»" sobre cada endpoint de C#, que genera la petición en el `.http` del proyecto
- [x] F12.15 Menú nativo "Datos" y comandos de paleta para EF Core y HTTP
- [x] F12.16 Pruebas: 82 nuevas (EF Core, esquema, formato `.http`, envío real contra un servidor y endpoints)

### Fase 13 — Registro estructurado, linter de arquitectura y terminal en la nube
- [x] F13.1 Parser de registro (`src/shared/log-events.ts`): Serilog, consola de .NET, NLog y CLEF
- [x] F13.2 Marcos de pila reconocidos por su forma, no por las palabras `at`/`in` (están traducidas)
- [x] F13.3 Pestaña "Registro" con pastillas por nivel, cuentas y filtro de texto
- [x] F13.4 Detalle desplegable por evento: excepción y traza completa
- [x] F13.5 Marcos clicables que abren el `.cs` en su línea exacta
- [x] F13.6 Repintado con freno de 400 ms para que una aplicación arrancando no bloquee el panel
- [x] F13.7 Modelo de reglas de arquitectura (`src/shared/architecture-rules.ts`): capas y dependencias permitidas
- [x] F13.8 Aviso `DF1001` por referencia de proyecto prohibida entre capas
- [x] F13.9 Aviso `DF1002` por `using` prohibido, con su línea exacta
- [x] F13.10 Aviso `DF1003` por paquete de infraestructura dentro del dominio o los puertos
- [x] F13.11 Los avisos van al panel de problemas y al margen del editor, con propietario propio de marcadores
- [x] F13.12 Modelo de Docker (`src/shared/docker.ts`) y servicio que lee el estado del motor
- [x] F13.13 Canal `terminal:context`: contenedores, imágenes y scripts del `package.json`
- [x] F13.14 Sugerencias de `docker` y `docker compose`, con contenedores e imágenes reales
- [x] F13.15 Sugerencias de la CLI de Azure por grupos (`webapp`, `group`, `sql`, `acr`, `containerapp`)
- [x] F13.16 Sugerencias de `npm` con los scripts reales del `package.json`, y banderas de `node`
- [x] F13.17 Corrección en las plantillas: el `outputTemplate` de Serilog escribía la hora literal
- [x] F13.18 Pruebas: 80 nuevas (registro, arquitectura, Docker y sugerencias de terminal)

### Fase 14 — Contenedores y Docker Compose
- [x] F14.1 Parser propio del subconjunto de YAML de Compose (`src/shared/compose.ts`)
- [x] F14.2 Modelo de servicio: imagen o `build`, `container_name`, puertos, dependencias y perfiles
- [x] F14.3 Cruce entre lo declarado y lo que corre (`matchComposeState`), como función pura
- [x] F14.4 Búsqueda de archivos de Compose en la raíz y un nivel por debajo
- [x] F14.5 Canales IPC `docker:state`, `docker:compose-files`, `docker:compose-read`, `docker:compose-run`, `docker:container-run`
- [x] F14.6 Validación de los canales: ruta dentro del workspace, nombre de archivo de Compose y nombres acotados
- [x] F14.7 Sexta herramienta de la barra de actividad: panel de contenedores
- [x] F14.8 Cabecera con archivo, recuento `n/m arriba` y botones Levantar / Bajar / Registro
- [x] F14.9 Fila por servicio con punto de estado, icono por tipo, nombre real y puertos
- [x] F14.10 Acciones por servicio: arrancar, parar, reiniciar y ver el registro
- [x] F14.11 Contenedores ajenos al compose en una sección aparte, con arrancar/parar/registro/eliminar
- [x] F14.12 Puerto como enlace sólo para lo que se abre en un navegador (Seq, RabbitMQ, MailHog)
- [x] F14.13 Con Docker apagado el panel sigue enseñando los servicios declarados (ADR-033)
- [x] F14.14 Modo de diagnóstico `--ui=containers` y entradas en el menú "Datos"
- [x] F14.15 Pruebas: 31 nuevas (YAML, servicios, puertos, comandos y correspondencia con el motor)
- [x] F14.16 El proceso depurado tiene canal, pastilla, puerto y parada propios (v1.8.1, ADR-034)
- [x] F14.17 El indicador de una tarea de larga duración es un punto verde, no un spinner (v1.8.1)

### Fase 15 — Explorador de pruebas, sintaxis semántica, túneles, métricas y auditoría
- [x] F15.1 Capacidad `textDocument/semanticTokens/full` declarada de verdad (las listas iban vacías)
- [x] F15.2 Modelo puro de tokens semánticos (`src/shared/semantic-tokens.ts`): descodificación relativa,
      normalización de los nombres de Roslyn y reempaquetado para Monaco
- [x] F15.3 Proveedor de tokens semánticos en el puente de Monaco, con repintado al llegar la leyenda
- [x] F15.4 Paleta de sintaxis estilo Visual Studio 2026 en los dos temas, con contraste AA verificado
- [x] F15.5 `solution/open`: Roslyn no carga nada hasta que se le abre la solución (ADR-039)
- [x] F15.6 Modelo puro del explorador de pruebas (`src/shared/test-explorer.ts`): descubrimiento por
      texto, árbol, filtros de VSTest y lectura de resultados
- [x] F15.7 Servicio de pruebas: recorrido de los proyectos de pruebas y `dotnet test` con logger TRX
- [x] F15.8 Resultados leídos del TRX, que es invariante; consola sólo como camino degradado (ADR-036)
- [x] F15.9 Panel lateral "Pruebas": árbol proyecto → clase → prueba, estados, filtro y "Ejecutar todas"
- [x] F15.10 Lentes de código "▶ Ejecutar prueba" y "Depurar" sobre cada `[Fact]` y `[Theory]`
- [x] F15.11 Los fallos van al panel de problemas con archivo, línea, mensaje del assert y traza
- [x] F15.12 Insignia de pruebas en rojo sobre el icono de la barra de actividad
- [x] F15.13 Modelo puro de túneles (`src/shared/dev-tunnel.ts`) con escáner de salida por líneas
- [x] F15.14 Botón "Crear túnel público" en la barra superior, con la URL clicable y el aviso
- [x] F15.15 Modelo puro de contadores (`src/shared/perf-counters.ts`): dos generaciones de nombres
- [x] F15.16 Pestaña "Métricas": CPU, montón, conjunto de trabajo, reserva, GC por generación y HTTP
- [x] F15.17 Sesión de `dotnet-counters collect` leyendo el CSV de forma incremental (ADR-038)
- [x] F15.18 Modelo puro de la auditoría de NuGet (`src/shared/nuget-audit.ts`): JSON y tabla degradada
- [x] F15.19 Sección "Seguridad" en el panel de NuGet: gravedad, CVE/GHSA y transitivos
- [x] F15.20 Insignia de paquetes con aviso sobre el icono de NuGet
- [x] F15.21 Modos de diagnóstico `--ui=tests`, `--ui=tests-run`, `--ui=metrics`, `--ui=audit`
- [x] F15.22 `--probe=` espera promesas: sirve para medir una llamada IPC, no sólo el DOM
- [x] F15.23 La salida de error del servidor de lenguaje llega a la consola en vez de perderse
- [x] F15.24 Pruebas: 165 nuevas (tokens semánticos, pruebas, túneles, contadores y auditoría)

### Fase 16 — Servidor de lenguaje: versión fijada, instalación verificada y respaldo automático
- [x] F16.1 Política de versiones de Roslyn (`src/shared/lsp-versions.ts`): versión fijada y
      verificada, descarte de compilaciones de prueba y orden por banda (ADR-040)
- [x] F16.2 Manifiesto de instalación con tamaño y hash por archivo (`src/shared/toolchain-manifest.ts`)
- [x] F16.3 Verificación superficial en cada arranque y profunda tras un fallo (ADR-041)
- [x] F16.4 El extractor se niega a escribir un archivo que no mide lo que declara el ZIP
- [x] F16.5 La descarga comprueba `content-length`: un `.nupkg` cortado ya no se extrae
- [x] F16.6 Detección del servidor roto por stderr y por nombre de tipo de excepción (ADR-042)
- [x] F16.7 Un cierre que nadie ha pedido es un fallo aunque el código de salida sea 0 (ADR-042)
- [x] F16.8 `workspace/configuration` se contesta con un array, no con `null` (ADR-043)
- [x] F16.9 Cuarentena de versiones por RID, con indulto si la culpa era de la copia (ADR-044)
- [x] F16.10 Conmutación automática y transparente a OmniSharp, con el motivo en la barra de estado
- [x] F16.11 Pruebas: 40 nuevas (política de versiones, detección, cuarentena, instalación y protocolo)
- [x] F16.12 Verificado sobre la aplicación real: hover, completado, símbolos y 1440 números de
      tokens semánticos con Roslyn 4.14.0-3.26423.7, y OmniSharp v1.39.15 sirviendo lo mismo
- [x] F16.13 NetCoreDbg se instala y se verifica por el mismo camino: `installArchive` + `verifyInstall`
- [x] F16.14 Su descarga comprueba `content-length` e informa del progreso, que antes iba siempre a null
- [x] F16.15 Prueba de seguridad que vigila que ningún adquisidor vuelva a declararse su marcador
- [x] F16.16 Pruebas: 6 nuevas del depurador, con el constructor de ZIP movido a un fixture compartido


### Fase 17 — Actualizaciones automáticas y explorador de extensiones de Open VSX
- [x] F17.1 Modelo puro de actualizaciones (`src/shared/updates.ts`): SemVer con prelanzamientos,
      lectura del feed de releases, elección de artefacto por plataforma y arquitectura (ADR-045)
- [x] F17.2 `updater-service.ts`: comprobación 5 s después del arranque y bajo demanda, descarga con
      verificación de `content-length` y estado en streaming hacia el renderer
- [x] F17.3 La instalación se aplica al cerrar (`before-quit`), con el instalador desprendido del
      proceso; lo pendiente se persiste en `updates/pending.json` y sobrevive a un cierre feo (ADR-046)
- [x] F17.4 Canales `update:state`, `update:check`, `update:download`, `update:dismiss` y
      `update:apply-on-quit`, más el evento `event:update-state`
- [x] F17.5 Tarjeta flotante (`src/renderer/views/update-card.ts`): título con la versión, notas de
      la publicación, barra de descarga y "Reiniciar y aplicar"
- [x] F17.6 "Descartar" no es "no quiero": oculta la tarjeta, sigue descargando e instala al cerrar
- [x] F17.7 Interruptor "Buscar actualizaciones automáticamente" y botón "Buscar ahora" en Ajustes,
      con el estado de la última comprobación
- [x] F17.8 Modelo puro del registro (`src/shared/open-vsx.ts`): URLs, lectura de la respuesta,
      identidad válida y lista blanca de hosts de descarga (ADR-047)
- [x] F17.9 Modelo puro del formato `.vsix` (`src/shared/vsix.ts`): manifiesto, carpeta de destino y
      reparto de las contribuciones entre las que aquí sirven y las que no (ADR-048)
- [x] F17.10 `open-vsx-service.ts`: búsqueda y ficha contra `https://open-vsx.org/api`, con caché corta
- [x] F17.11 `extension-installer.ts`: descarga verificada del `.vsix` e instalación en
      `userData/extensions/` con `installArchive` + `verifyInstall`, sin marcador propio (ADR-041)
- [x] F17.12 Panel lateral "Extensiones" con buscador, filtro por categoría, instaladas arriba y
      resultados debajo; los iconos se dibujan localmente (ADR-049)
- [x] F17.13 Cada extensión instalada dice qué aporta de verdad y qué no tiene efecto en DotForge
- [x] F17.14 Menú, paleta de comandos y modos de diagnóstico `--ui=extensions` y `--ui=update`
- [x] F17.15 Pruebas: 90 nuevas — 82 unitarias (SemVer y feed de releases 35, cliente de Open VSX 26,
      formato `.vsix` con instalación real en disco 21) y 8 de seguridad de las dos superficies de
      descarga nuevas
- [x] F17.16 Verificado sobre la aplicación real: búsqueda en Open VSX con 16 920 extensiones,
      instalación y desinstalación de un `.vsix` de verdad, y la tarjeta de actualización a la vista

---

### Fase 18 — Bugs de usabilidad y rendimiento, y dos mejoras de UX
- [x] F18.1 Instalar deja de bloquear el hilo principal: `readEntryAsync` (`inflateRaw` en el pool de
      libuv) y `sha256Async` (troceado con cesión del bucle), y fuera `existsSync` de los dos
      instaladores (ADR-051)
- [x] F18.2 Pruebas de responsividad que miden vueltas del bucle de eventos, no tiempo, cada una con
      su control por el camino síncrono
- [x] F18.3 `focus-guard.ts` + `repaintPreservingFocus`: el repintado devuelve el foco y el cursor al
      campo marcado con `data-focus-key` (ADR-052)
- [x] F18.4 Las búsquedas de NuGet y de Open VSX descartan las respuestas que llegan tarde
- [x] F18.5 La casilla "pre" de NuGet se pinta desde el estado en vez de reconstruirse en blanco
- [x] F18.6 `editor-state.ts`: una única regla para el estado de escritura del editor, recalculada en
      cada punto de control y en el `finally` de toda operación asíncrona (ADR-053)
- [x] F18.7 `save()` captura sus fallos y avisa; el autoguardado guarda la pestaña que cambió, no la
      que esté activa al saltar el temporizador
- [x] F18.8 `nuget-install.ts`: plan de instalación en varios proyectos, en serie, emparejando por
      `taskId`, con progreso y resumen que nombra los que fallan
- [x] F18.9 Panel de NuGet con casillas por proyecto, "Todos"/"Ninguno", barra de progreso global y
      botón que dice en cuántos proyectos va a entrar el paquete
- [x] F18.10 Recargar la solución deja de tirar la selección y el plan en marcha: sólo se reinicia el
      estado al cambiar de solución de verdad
- [x] F18.11 `activity-bar.ts`: orden de la barra por identificador, normalizado al leerlo, con
      "Ajustes" fijo bajo el separador (ADR-054)
- [x] F18.12 Reordenar arrastrando los iconos, persistido en `activityBar.order`, con "Restaurar el
      orden" en Ajustes cuando hay algo que deshacer
- [x] F18.13 Los modos `--ui=` pulsan por `data-tool-id`, con prueba estructural que lo vigila
- [x] F18.14 La prueba de humo mata el árbol de procesos de Electron: la suite dejaba de poder salir
      tras un timeout
- [x] F18.15 Verificado sobre la aplicación real con `--probe=`: foco y cursor conservados tras el
      rebote y 30 resultados repintados, instalación real en los 6 proyectos de una solución Clean,
      arrastre persistido y `--ui=` funcionando con la barra reordenada

---

### Fase 19 — Terminal navegable y barra de menú completa
- [x] F19.1 Modelo puro de navegación de la terminal (`src/shared/terminal-cwd.ts`): `cd`, `chdir`,
      `Set-Location`, `sl`, el `cd /d` de cmd, `D:` a secas, `pwd`/`Get-Location` (ADR-055)
- [x] F19.2 `terminal-session.ts`: resolución contra el disco, comprobación del destino y memoria del
      anterior para `cd -`
- [x] F19.3 `terminal:run` clasifica antes de lanzar; canal `terminal:cwd`; el contexto se sincroniza
      al abrir, al cerrar y al arrancar por línea de comandos
- [x] F19.4 Ruta en el prompt, relativa al workspace o con `~`, recortada por el medio si no cabe, y
      con la ruta completa en el `title`
- [x] F19.5 El foco de la terminal sobrevive a los repintados del panel (`repaintPreservingFocus`)
- [x] F19.6 Plantilla del menú como dato puro (`src/shared/menu-template.ts`), con `menu.ts` limitado
      a traducirla a Electron (ADR-056)
- [x] F19.7 Menús Archivo (abrir solución, recientes, cerrar solución), Editar (buscar, formatear,
      ir a la definición, renombrar, asistente en línea), Ver (todas las vistas y los dos temas),
      Datos (EF Core, migraciones, cliente HTTP), IA, Git, Compilar, Depurar y Ayuda
- [x] F19.8 Submenú de soluciones recientes, con las no disponibles deshabilitadas y el menú
      reinstalándose al abrir una solución
- [x] F19.9 `ROLE_ACCELERATORS` y comprobación de choques contando los aceleradores heredados de los
      `role` de Electron
- [x] F19.10 Modo de diagnóstico `--menu-dump`: vuelca el menú ya construido por Electron
- [x] F19.11 Pruebas: 75 nuevas (34 del modelo de la terminal, 20 de la sesión con carpetas de
      verdad, 21 del menú) y 2 estructurales de endurecimiento

---

### Fase 20 — Buscar dentro de los archivos
- [x] F20.1 Modelo puro de la búsqueda (`src/shared/file-search.ts`): texto plano, mayúsculas,
      palabra completa y expresión regular, con el mensaje del motor conservado
- [x] F20.2 Globs de inclusión y exclusión (`*`, `**`, `?`, `{a,b}`, `tests/`), con `!` como
      negación dentro de la propia caja de inclusión
- [x] F20.3 Recorte de la línea que se enseña, con la columna dentro del recorte y la de verdad
      viajando aparte para el editor
- [x] F20.4 Saneado de lo que llega del renderer (`coerceSearchOptions`): tipos, longitudes y topes
- [x] F20.5 `search-service.ts`: recorrido asíncrono del workspace, ocho lecturas a la vez sobre un
      mismo generador, sin nada síncrono (ADR-051)
- [x] F20.6 Directorios de construcción y dependencias saltados por nombre; binarios descartados por
      extensión y, los que se cuelan, por el byte cero; tope de tamaño por archivo
- [x] F20.7 Resultados emitidos por lotes mientras el recorrido sigue, y cancelación: una búsqueda
      nueva abandona a la anterior, que lo nota y se para
- [x] F20.8 Canales `search:in-files` y `search:cancel` más el evento `event:search-progress`, con
      la raíz tomada del guardián de rutas y no del renderer (ADR-057)
- [x] F20.9 Undécima herramienta de la barra de actividad y panel `search.ts`: caja, banderas
      `Aa`/`ab`/`.*` y campos plegables de archivos a incluir y a excluir
- [x] F20.10 Rebote de 300 ms con el foco y el cursor conservados en el repintado (ADR-052), y
      descarte de las respuestas que llegan tarde por número de orden
- [x] F20.11 Resultados agrupados por archivo, plegables, con recuento por archivo y total, y la
      coincidencia resaltada dentro de la línea
- [x] F20.12 Pulsar un resultado abre el archivo en su línea y columna exactas **con la coincidencia
      seleccionada** (`EditorView.open` acepta `length`)
- [x] F20.13 Comando `search.findInFiles` con `Ctrl+Shift+F`, entrada "Buscar en los archivos…" en
      Editar y en Ver; el filtro por nombre del explorador conserva su comando y pasa a `Ctrl+P`
- [x] F20.14 Modo de diagnóstico `--ui=search`, que además escribe en la caja
- [x] F20.15 Pruebas: 74 nuevas (49 del modelo, 18 del servicio con carpetas de verdad, 5 de
      seguridad de la superficie nueva, 2 del menú y 2 de la barra de actividad)
- [x] F20.16 Verificado sobre la aplicación real: 294 resultados en 23 archivos en 20 ms sobre una
      solución Clean, salto a `Ln 4, Col 36` con `Product` seleccionado, foco y cursor conservados
      al escribir, y filtros glob bajando de 294 a 133

---

### Fase 21 — Múltiples perfiles de terminal y tres bugs de arranque y de uso
- [x] F21.1 `src/shared/json-text.ts`: `stripBom` y `parseJsonText`. La marca de orden de bytes UTF-8
      de Windows deja de romper el parseo de los JSON que el IDE no escribe (ADR-058)
- [x] F21.2 Aplicado a los diez lectores que leen JSON ajeno: `launchSettings.json`, `package.json`,
      `appsettings*.json`, manifiestos de `.vsix` y de instalación, ajustes, perfiles de inicio,
      llavero y actualización pendiente
- [x] F21.3 `selectProfile` prefiere HTTPS cuando no hay coincidencia de nombre: las plantillas del
      SDK declaran `http` primero y era justo el perfil sin TLS el que se arrancaba
- [x] F21.4 `--launch-profile <nombre>` explícito en `dotnet run` y `dotnet watch`, resuelto por el
      proceso principal; `launchProfileArgs` acota la bandera a los verbos que la aceptan
- [x] F21.5 `src/renderer/views/confirm-dialog.ts` (nuevo): diálogo modal propio y asíncrono, con
      Escape, foco atrapado dentro del cuadro, foco previo devuelto y tercer botón opcional
- [x] F21.6 `EditorView.confirmDiscard`: recalcula la editabilidad y devuelve el foco a Monaco en un
      `finally`, así que ninguna respuesta —ni un fallo— deja el editor sin teclado
- [x] F21.7 `ConfirmationLock`: como mucho un modal a la vez y el cerrojo se suelta pase lo que pase
- [x] F21.8 Cerrar la ventana con cambios sin guardar pregunta de verdad: en Electron, un
      `preventDefault()` en `beforeunload` no enseña ningún diálogo y deja el aspa muerta
- [x] F21.9 Las otras cuatro confirmaciones bloqueantes (git, EF Core, contenedores, extensiones)
      pasan al mismo diálogo
- [x] F21.10 `src/shared/terminal-profiles.ts` (nuevo): catálogo de perfiles, filtrado por
      plataforma, saneado del identificador y numeración de pestañas por perfil
- [x] F21.11 `src/main/services/terminal-pty-service.ts` (nuevo): sesiones de `node-pty` con carga
      tardía y tolerante, tope de sesiones, tope de escritura y `programExists` (ADR-059)
- [x] F21.12 Canales `terminal:profiles`, `terminal:create`, `terminal:write`, `terminal:resize` y
      `terminal:dispose`, más los eventos `event:terminal-data` y `event:terminal-exit`
- [x] F21.13 Panel: tira de pestañas de terminal con su aspa, botón `+` con menú de intérpretes y lo
      no disponible atenuado con el motivo escrito
- [x] F21.14 `src/renderer/xterm-bridge.ts` (nuevo) y xterm.js servido desde `build/vendor/xterm/`,
      como Monaco, con los colores tomados del tema activo
- [x] F21.15 Limpieza: cerrar la pestaña cierra la sesión; `before-quit`, `process.on('exit')` y el
      cierre de la ventana se llevan todos los árboles de procesos
- [x] F21.16 Comando "Nueva terminal" en la paleta y en el menú Ver
- [x] F21.17 Modos de diagnóstico `--ui=unsaved` y `--ui=terminal-pty`
- [x] F21.18 Pruebas: 37 nuevas (29 de perfiles, sesiones y arranque, 8 estructurales de seguridad de
      la superficie nueva) más `tests/unit/pty-session.probe.mjs`, que abre un intérprete de verdad
      en un proceso aparte
- [x] F21.19 Verificado sobre la aplicación real: `echo` de ida y vuelta en PowerShell, tres pestañas
      a la vez, cierre de una sola, cero procesos huérfanos al salir, y el editor recuperando el
      teclado tras las dos respuestas del aviso de cambios sin guardar

### Fase 22 — Publicación de releases: darle combustible al actualizador
- [x] F22.1 Job `publish` en `.github/workflows/release.yml`, con `contents: write` sólo en él y el
      resto del workflow en sólo lectura (ADR-060)
- [x] F22.2 Tres disparos que convergen: `push` de un tag `v*`, `release: published` y
      `workflow_dispatch` con entradas `tag` y `draft`
- [x] F22.3 El tag se resuelve por variables de entorno, no interpolado dentro del shell, y se valida
      como SemVer antes de seguir
- [x] F22.4 La CI se para si el tag y `package.json` no dicen la misma versión: publicarlo así deja
      al IDE reinstalando la misma versión en cada cierre, para siempre
- [x] F22.5 `scripts/lib/release-notes.mjs` (nuevo): composición pura del cuerpo de la release, con
      el recorte de la lista anunciado y sin marcas que se evaporen en la tarjeta del IDE
- [x] F22.6 `scripts/release-notes.mjs` (nuevo): tag anterior por orden de versión, rango de commits
      y artefactos de `dist/`; sirve a mano antes de empujar el tag
- [x] F22.7 `gh release create`/`edit` + `upload --clobber`, sin ninguna acción de terceros corriendo
      con el permiso de escritura
- [x] F22.8 Paso final que le pregunta a la API pública si la release aparece con artefactos:
      publicar no es lo mismo que estar publicado
- [x] F22.9 El actualizador entra en la lista de adquisidores: sus dos peticiones pasan por
      `requestHeaders` y su 403 por `rateLimitHint` (ADR-050)
- [x] F22.10 `HeaderOptions.userAgent`, para que el feed sepa desde qué versión se pregunta
- [x] F22.11 Pruebas: 33 nuevas — 22 del modelo de notas (contrato con `releaseNotesLines`
      incluido), 10 del contrato del workflow y 1 del alcance del agente
- [x] F22.12 Verificado ejecutando los pasos del workflow: los cinco caminos de resolución del tag y
      los cuatro escenarios de publicación contra un `gh` de mentira

### Fase 23 — Persistencia de las pestañas de terminal
- [x] F23.1 `src/shared/terminal-layout.ts` (nuevo): modelo puro de la disposición, saneado de lo
      que llega del renderer y del disco, y plan de reapertura (ADR-061)
- [x] F23.2 `src/main/services/terminal-layout-store.ts` (nuevo): una entrada por solución en
      `userData/terminal-layouts.json`, con poda por uso y lectura tolerante a la marca de orden de
      bytes (ADR-058)
- [x] F23.3 Canales `terminal:layout-save` y `terminal:layout-restore`; el `cwd` lo pone el proceso
      principal desde la sesión de la terminal, nunca el renderer (ADR-059)
- [x] F23.4 Se anota en cada cambio de pestaña, no al cerrar: abrir otra solución cambia la clave
      con la que se guarda
- [x] F23.5 El panel reabre las pestañas al abrir una solución, consumiendo la asistida del arranque
      en vez de duplicarla, y sólo sobre un panel intacto
- [x] F23.6 Un perfil que aquí no se puede abrir se salta y se dice cuántos, en vez de dejar
      pestañas muertas
- [x] F23.7 Ajuste "Restaurar las pestañas al abrir una solución", con la letra pequeña de qué
      significa restaurar escrita al lado
- [x] F23.8 Pruebas: 26 nuevas del modelo y del almacén, más 2 de seguridad de la superficie nueva
- [x] F23.9 Verificado sobre la aplicación real: tres pestañas reabiertas en orden y con la activa
      correcta, sin crecer entre reaperturas, y el ajuste apagado dejando el panel limpio

### Fase 24 — Claude Code en la terminal y consumo declarativo de extensiones
- [x] F24.1 Perfil "Claude Code" en el catálogo, con las tres formas en que se instala declaradas
      como alternativas del propio catálogo (ADR-062)
- [x] F24.2 `resolveProgram` devuelve la ruta resuelta, no el nombre: en Windows, `CreateProcess`
      sólo prueba `.exe` al buscar por `PATH` y un `.cmd` se encuentra y no se puede lanzar
- [x] F24.3 Un perfil no disponible dice **cómo** instalarlo (`unavailableReason`), no sólo que falta
- [x] F24.4 Comando `ai.openClaudeTerminal` en la paleta y en el menú IA, con `Ctrl+Shift+C`
- [x] F24.5 Abre **o enfoca**: pulsar el atajo dos veces no deja dos sesiones abiertas
- [x] F24.6 `claude` en la terminal asistida es una orden del intérprete, como `cd`: abre su pestaña
      en vez de fallar por la lista blanca
- [x] F24.7 Sugerencias de la CLI de Claude y de las órdenes de barra de una sesión
- [x] F24.8 Modo de diagnóstico `--ui=claude`, que ejercita la cadena entera por la paleta
- [x] F24.9 Los modos de diagnóstico no restauran pestañas de terminal: reabrirlas dejaba el bucle
      de eventos vivo y `--smoke-test` no terminaba
- [x] F24.10 `src/shared/vsix-contributions.ts` (nuevo): modelo puro de temas y fragmentos, con la
      normalización de colores que Monaco exige y el nombre de tema que Monaco acepta
- [x] F24.11 `src/main/services/extension-contributions.ts` (nuevo): lectura del disco, cadena de
      `include`, `.tmTheme` traducido desde su plist y validación de toda ruta del manifiesto
- [x] F24.12 Canal `extensions:contributions`, pedido al arrancar y tras instalar o desinstalar
- [x] F24.13 Los temas de extensión se registran en Monaco y se eligen desde Ajustes; el resto de la
      ventana usa el tema propio que declare su `uiTheme`, y el ajuste lo dice
- [x] F24.14 Los fragmentos se registran como proveedor de autocompletado, agrupados por lenguaje
- [x] F24.15 Pruebas: 69 nuevas (22 del perfil y las sugerencias, 47 de las contribuciones) más 2
      estructurales de seguridad
- [x] F24.16 Verificado sobre la aplicación real: una sesión de Claude Code por la paleta, y un tema
      y unos fragmentos de Open VSX aplicados en el editor
- [x] F24.17 Estabilización: el IntelliSense vuelve a la versión fijada del ADR-040. Un veto de
      cuarentena caduca con la versión del IDE que lo dictó, y la barra de estado distingue
      "vetada aquí" de "ya no está en el feed" (ADR-063)
- [x] F24.18 `shutdown` deja de mandarse con `params: null`, que mataba al servidor con una
      excepción .NET no controlada en vez de cerrarlo
- [x] F24.19 Prueba de contrato del ADR-040: la versión fijada es una constante literal y la
      selección es determinista, no se resuelve al vuelo


### Fase 25 — Publicación de proyectos (`dotnet publish`)
- [x] F25.1 `src/shared/dotnet-publish.ts` (nuevo): modelo puro de las opciones a los argumentos,
      con las banderas que dependen del RID y el saneado de la ruta de salida (ADR-064)
- [x] F25.2 `PublishSingleFile`, `PublishReadyToRun` y `PublishTrimmed` **sólo** con `--runtime`;
      el recorte además exige autocontenido. Se descartan aunque lleguen encendidas: las
      preferencias guardadas pueden traerlas con un modo que ya no las admite
- [x] F25.3 `publishOutputPath` reproduce la carpeta que compone el SDK en vez de rastrearla en la
      salida: el mensaje de MSBuild que la anuncia está traducido (ADR-028)
- [x] F25.4 `publishProject` en `dotnet-service.ts`, por el canal de tareas: punto de progreso,
      salida en el panel inferior y botón de cancelar, como cualquier `dotnet build`
- [x] F25.5 Canal propio `dotnet:publish`, **fuera** de `TASK_KINDS`: dentro, `dotnet:run-task`
      aceptaría un `extraArgs` cualquiera detrás del verbo `publish`
- [x] F25.6 `src/main/services/publish-profile-store.ts` (nuevo): últimas opciones por proyecto en
      `userData/publish-profiles.json`, saneadas al leer con la misma función que lo del renderer
- [x] F25.7 `src/renderer/views/publish-dialog.ts` (nuevo): modal propio con las casillas atenuadas
      **y el motivo escrito al lado** cuando el modo no las admite (ADR-023)
- [x] F25.8 "Publicar…" en el menú contextual, sólo en proyectos que producen algo ejecutable
- [x] F25.9 Resumen en el panel al terminar, con `[Abrir carpeta]` al final de la línea; la línea
      con acción se empareja **por `taskId`**, nunca "la que esté corriendo"
- [x] F25.10 Los tres bloques de `spawn` casi iguales de `dotnet-service.ts` pasan a ser uno: el
      aviso de "no se ha podido ejecutar dotnet" sólo estaba en uno de los tres
- [x] F25.11 Modos de diagnóstico `--ui=publish` y `--ui=publish-run`
- [x] F25.12 Pruebas: 48 del modelo, 13 del almacén y 7 estructurales de seguridad
- [x] F25.13 Verificado sobre la aplicación real: `dotnet publish` de un Blazor en 5,8 s, artefactos
      en el disco, resumen con la ruta y el botón, y las opciones anotadas en `userData`

### Fase 26 — Barra lateral, pestañas y rutas que no caben
- [x] F26.1 `workbench.action.toggleSidebar` con `Ctrl+B`, en el menú **Ver > Barra lateral**, en la
      paleta y con un botón atenuado en la cabecera de la propia barra
- [x] F26.2 El identificador propio es `view.toggle-sidebar` y el de VS Code se acepta como alias:
      `Command` gana un campo `aliases` y `runCommandById` mira los dos
- [x] F26.3 `sidebarVisible` persistido; pulsar una herramienta con la barra escondida la trae de
      vuelta, y la barra de **actividad** no se esconde nunca (ADR-065)
- [x] F26.4 `EditorView.layout()` a mano: lo que cambia es la rejilla que envuelve al contenedor, no
      el contenedor, así que el `ResizeObserver` de Monaco llega un fotograma tarde
- [x] F26.5 `src/shared/editor-tabs.ts` (nuevo): a qué proyecto pertenece un archivo (prefijo de
      directorio más largo, por segmentos) y qué color le toca (ADR-065)
- [x] F26.6 El color se guarda por nombre de proyecto y no se deriva de la posición en la solución:
      derivarlo haría que crear un proyecto de pruebas recoloreara todos los demás
- [x] F26.7 Ocho tokens `--tab-project-N` en los dos temas; el renderer aplica la clase, nunca un
      color calculado
- [x] F26.8 `workbench.editor.tabPosition` (arriba, izquierda, derecha), resuelto entero en CSS con
      áreas de rejilla: mover un nodo en el DOM destruiría el contenedor de Monaco
- [x] F26.9 Con la tira a un lado, el canto exterior lleva el color del proyecto y el interior el
      acento de pestaña activa: puestos en el mismo borde, uno tapa al otro
- [x] F26.10 La ruta del aviso de cambios sin guardar deja de salirse del cuadro: `min-width: 0` en
      la columna, `overflow-wrap: anywhere`, alto máximo con desplazamiento y `title` entero
- [x] F26.11 Modos de diagnóstico `--ui=sidebar` y `--ui=tabs`
- [x] F26.12 Pruebas: 33 del modelo de pestañas
- [x] F26.13 Verificado sobre la aplicación real: tira a la izquierda con Monaco ocupando su área
      exacta (900/900 px), la marca pintando `#d78fbe`, la barra escondida dejando 1184/1184 px, y
      una ruta de 480 caracteres dentro del cuadro con su desplazamiento propio

### Fase 27 — El actualizador in-app deja de ser mudo en los dos extremos
- [x] F27.1 Aviso previo al cierre: `applyConfirmation` (puro) compone qué se va a cerrar, cuánto
      tarda, quién termina el trabajo y si la aplicación vuelve sola, con un texto por plan
- [x] F27.2 El botón dice lo que hace: `applyActionLabel` da "Cerrar e instalar" o "Abrir
      instalador", y ninguno promete un reinicio que el IDE no hace (ADR-066)
- [x] F27.3 `planKind` en `UpdateState`: el renderer decide con un dato, no comparando la frase de
      `plan`, que es texto de presentación
- [x] F27.4 `/S` pasa a llevar `--force-run`: un NSIS asistido instalado en silencio no relanza la
      aplicación por su cuenta, y la tarjeta lo prometía
- [x] F27.5 `judgePending` (puro): los cuatro veredictos sobre el registro pendiente —aplicado, no
      completado, pendiente y caduco— a partir de la versión que corre y del intento anotado
- [x] F27.6 `attempts` en `pending.json`, anotado **al lanzar** el instalador: para cuando termina
      ya no hay proceso que pueda escribir nada
- [x] F27.7 Las notas y el enlace de la release viajan con el registro: después de instalarla, el
      feed ya no las tiene
- [x] F27.8 `state.outcome` con `outcomeHeadline` / `outcomeMessage`: el "✅ ¡Actualizado con éxito
      a la vX!" con las novedades, y el "⚠️ La actualización a la vX no se completó" con las dos
      causas posibles y el botón para reintentar (ADR-066)
- [x] F27.9 Fuera del `status` a propósito: la comprobación automática de los cinco segundos
      publica `up-to-date` y se habría llevado el aviso por delante
- [x] F27.10 `update:acknowledge` con acción propia: cerrar una noticia no es posponer una
      actualización, y `dismiss` armaba `applyOnQuit` a ciegas
- [x] F27.11 El instalador se lanza en `will-quit` y no en `before-quit`: ese cierre todavía se
      puede cancelar, y el aviso de cambios sin guardar lo cancela
- [x] F27.12 Modos de diagnóstico `--ui=update-done`, `--ui=update-failed` y `--ui=update-confirm`
- [x] F27.13 Pruebas: 30 nuevas (18 del modelo puro, 12 del ciclo de vida del servicio con un
      `pending.json` de verdad en el disco, una de ellas estructural sobre el evento de cierre)
- [x] F27.14 Verificado sobre la aplicación real: los tres estados pintados y medidos con `--probe=`

### Fase 28 — Copiar y pegar en las pestañas de intérprete
- [x] F28.1 `terminal-clipboard.ts` (puro): qué gesto es cada tecla y cada clic. `Ctrl+C` con
      selección copia y sin ella interrumpe; `Ctrl+V`, `Ctrl+Shift+V` y `Shift+Insert` pegan;
      `Ctrl+Shift+C` y `Ctrl+Insert` copian; el resto llega al intérprete tal cual (ADR-067)
- [x] F28.2 En macOS no se toca nada: `Cmd+C` / `Cmd+V` ya los atienden los `role` del menú y
      `Ctrl+C` en un Mac es siempre interrumpir
- [x] F28.3 Botón secundario en Windows como en la consola: con selección copia y la suelta; sin
      ella pega
- [x] F28.4 Canal `clipboard:read-text` / `clipboard:write-text`: texto plano, sólo para la
      terminal. `navigator.clipboard` no sirve porque la ventana deniega todos los permisos
- [x] F28.5 `attachClipboard` en `xterm-bridge.ts`: manejador previo de teclado con
      `preventDefault()` en los gestos atendidos, para que el `role: 'paste'` del menú no pegue
      una segunda vez
- [x] F28.6 Pruebas: 18 (15 del modelo puro y 3 estructurales sobre el cableado)
- [x] F28.7 Verificado con teclas de verdad sobre la ventana: `Ctrl+V` en `cmd.exe` pintaba `^V`
      antes del cambio; después, `Shift+Insert` pega una sola vez y `Ctrl+C` sin selección sigue
      interrumpiendo
- [x] F28.8 `cls` comprobado y **no reproducido**: ConPTY emite el borrado fila a fila más `ESC[3J`
      y xterm lo aplica, en desarrollo y en la 2.8.0 instalada. Si vuelve a verse, hace falta el
      contexto exacto (tamaño del panel, qué había antes)

### Fase 29 — El IDE siempre arranca después de actualizarse
- [x] F29.1 `removeUpdatesDir` no lanza nunca: limpiar una descarga ya aplicada es tarea doméstica
      y no puede impedir que el IDE abra una ventana (ADR-068)
- [x] F29.2 Reintentos en el borrado: `rm` reintenta ante `EPERM`, que es exactamente el caso —el
      instalador sigue vivo porque acaba de relanzar el IDE
- [x] F29.3 Recogida en el arranque siguiente: sin registro pendiente nadie volvía a mirar la
      carpeta, así que un instalador huérfano de 130 MB se quedaba en el disco de por vida
- [x] F29.4 `updaterService.initialize` dentro de su propio `try`: es un servicio accesorio
- [x] F29.5 `catch` en la cadena de arranque: informa y cierra, en vez de dejar un proceso vivo y
      sin ventana que además sostiene el bloqueo de instancia única
- [x] F29.6 Una segunda instancia sale con `app.exit(0)` y no con `app.quit()`, que es una petición
      y deja el módulo ejecutándose — y en este archivo `will-quit` lanza instaladores
- [x] F29.7 `second-instance` abre ventana si no hay ninguna y el arranque ya terminó: convierte el
      callejón sin salida en el gesto que el usuario acaba de hacer
- [x] F29.8 `--updated` en el plan de instalación: hace que NSIS **espere** a que el IDE termine de
      cerrarse, como `CloseApplications=yes` en Inno Setup
- [x] F29.9 Pruebas: 6 nuevas (una reproduce el `EPERM` de verdad en Windows, dos son estructurales
      sobre la cadena de arranque, y las demás cubren la recogida y las banderas)
- [x] F29.10 Verificado sobre la aplicación real, antes y después, con un `userData` aislado y un
      instalador falso en marcha: el código publicado se queda sin ventana con
      `UnhandledPromiseRejectionWarning: EPERM` y hay que matarlo; el corregido escribe un aviso y
      llega a `SMOKE_OK`

---

## Decisiones técnicas (ADR corto)

### ADR-001 — Base del IDE: Electron + Monaco (no fork de VS Code, no Theia)
**Fecha:** 2026-08-23
**Contexto:** Se necesita un IDE de escritorio empaquetable para Windows y macOS, 100% open source.
**Opciones:**
- (a) Fork de VS Code (Code-OSS): máxima funcionalidad, pero el árbol pesa GB, la build tarda
  decenas de minutos, y el marketplace y las fuentes tipográficas de Microsoft no son
  redistribuibles sin trabajo de limpieza.
- (b) Eclipse Theia: buena base, pero arrastra un stack Inversify + build compleja y su modelo
  de extensión añade una capa de indirección importante para lo que se necesita aquí.
- (c) Electron + Monaco Editor + shell propio: control total, build en segundos, superficie de
  seguridad pequeña y auditable, artefactos ligeros.
**Decisión:** (c) Electron + Monaco con shell propio.
**Consecuencias:** hay que implementar a mano el cliente LSP, el bridge DAP, el explorador y los
paneles — que es exactamente el trabajo diferencial de este producto. Se pierde compatibilidad
directa con extensiones VSIX; se mitiga apuntando el registro a Open VSX para futuras versiones.

### ADR-002 — Sin MediatR en las plantillas generadas
**Fecha:** 2026-08-23
**Contexto:** El patrón CQRS del blueprint DDD necesita un despachador de comandos/consultas.
MediatR es el estándar de facto, pero pasó a licencia comercial en versiones recientes.
**Opciones:** (a) MediatR, (b) alternativa OSS de terceros, (c) despachador propio ~120 líneas.
**Decisión:** (c) `IDispatcher` propio con registro por reflexión sobre el ensamblado de Application.
**Consecuencias:** cero fricción de licencia para quien genere una solución, menos superficie de
dependencias, y el código queda didáctico. A cambio no hay pipeline behaviors de terceros:
se incluye un pipeline de comportamientos propio (logging + validación) para cubrir el caso común.

### ADR-045 — Actualizaciones sin `electron-updater`
**Fecha:** 2026-08-24
**Contexto:** El IDE tiene que saber que hay una versión nueva y aplicarla sin que el usuario vaya a
buscar un instalador a mano.
**Opciones:** (a) `electron-updater`; (b) leer la API pública de releases y descargar el artefacto.
**Decisión:** (b).
**Consecuencias:** `electron-updater` da actualizaciones diferenciales y verificación de firma, pero
exige artefactos **firmados** y un canal de publicación (`latest.yml`, que genera el publicador de
electron-builder). Aquí no hay certificado y `electron-builder.yml` declara `publish: null`, así que
ese camino no está disponible hoy. La alternativa reutiliza exactamente el patrón que ya sostiene el
toolchain: feed público, descarga con `content-length` comprobado y artefacto guardado en `userData`.
A cambio, la actualización es completa (unos 120 MB) y la integridad depende de HTTPS, no de una
firma; cuando haya certificado, migrar es cambiar este servicio, no la interfaz.

### ADR-046 — La actualización se aplica al cerrar, y "Descartar" no significa "no"
**Fecha:** 2026-08-24
**Contexto:** Reemplazar los archivos de la aplicación mientras está abierta no se puede hacer, y
pedir "reinicia ahora" a alguien que está a mitad de un método es la forma más rápida de que las
actualizaciones se ignoren para siempre.
**Decisión:** el único camino de instalación es `app.on('before-quit')`. "Reiniciar y aplicar" cierra
el IDE para llegar ahí; "Descartar" esconde la tarjeta, **sigue descargando en segundo plano** y deja
la instalación programada para el próximo cierre.
**Consecuencias:** un solo camino que probar, y una actualización que se aplica sola sin que nadie
haya tenido que parar de trabajar. Lo pendiente se persiste en `updates/pending.json`: una promesa
que sólo vive en memoria no sobrevive a un cierre inesperado, y prometer una instalación que luego no
ocurre es peor que no prometerla. El instalador se lanza `detached`, porque el padre está
desapareciendo. En macOS no hay instalación silenciosa posible sin firma ni framework de
actualización: se abre el `.dmg` y se dice explícitamente que hay que arrastrar la app a
Aplicaciones, en vez de fingir que se ha instalado.

### ADR-047 — Extensiones de Open VSX, con el host de descarga en lista blanca
**Fecha:** 2026-08-24
**Contexto:** El marketplace de Microsoft no permite por licencia que lo consuma un producto que no
sea VS Code. Open VSX (Eclipse Foundation) sirve los mismos `.vsix` y sí lo permite; es lo que se
anticipó en la ADR-001.
**Decisión:** cliente propio contra `https://open-vsx.org/api`, con la petición hecha **desde el
proceso principal** y la URL de descarga validada contra una lista de hosts antes de pedirla.
**Consecuencias:** la CSP del renderer sigue sin permitir ningún origen remoto y el registro no ve
nada del equipo salvo la propia consulta. La validación del host no es ceremonia: la URL del `.vsix`
llega **dentro del JSON del registro**, es decir, es texto de la red que acaba siendo el origen de
algo que se escribe en el disco; sin comprobarla, quien pueda alterar esa respuesta elige de dónde se
baja el archivo. Si la respuesta trae una descarga de otro host, se descarta y se construye la
canónica. El paquete se instala con `installArchive` + `verifyInstall` (ADR-041), nunca con un
marcador propio.

### ADR-048 — Las extensiones se instalan; su código no se ejecuta, y se dice
**Fecha:** 2026-08-24
**Contexto:** DotForge no es VS Code: no tiene su host de extensiones ni su API. Un `.vsix` trae dos
cosas distintas —contribuciones declarativas (temas, fragmentos, gramáticas, lenguajes) y código de
activación— y sólo las primeras se pueden aprovechar sin implementar ese host entero.
**Opciones:** (a) no ofrecer extensiones hasta poder ejecutarlas; (b) instalarlas y callar; (c)
instalarlas y decir en cada ficha qué aporta y qué no tiene efecto aquí.
**Decisión:** (c). `describeContributions` reparte cada clave de `contributes` entre las dos listas.
**Consecuencias:** quien instale un depurador de Python ve, en la propia ficha, que su depurador no
va a funcionar aquí, en vez de deducirlo esperando a que pase algo. Un gestor que instala y calla se
percibe como roto; uno que explica su alcance se percibe como honesto. Cuando el IDE sepa consumir
gramáticas TextMate o temas de VS Code, la lista de "sirve" crece y no hay que tocar nada más.

### ADR-049 — Los iconos de las extensiones se dibujan, no se descargan
**Fecha:** 2026-08-24
**Contexto:** Cada extensión del registro publica un icono en una URL remota.
**Decisión:** se pinta una pastilla con las iniciales y un color derivado del identificador.
**Consecuencias:** es la misma decisión que ya se tomó con NuGet y por los mismos dos motivos: la CSP
del renderer declara `img-src 'self' data:` y no se va a relajar por unos iconos, y descargarlos le
contaría al registro qué extensiones está mirando el usuario. El color sale de un hash del
identificador, así que la misma extensión se ve siempre igual y la lista sigue siendo escaneable.
### ADR-050 — El token de GitHub sólo viaja a `api.github.com`
**Fecha:** 2026-08-24
**Contexto:** La adquisición de NetCoreDbg y de OmniSharp consulta la API de GitHub para saber cuál
es la última release. Sin autenticar, esa API permite 60 peticiones por hora **y por IP**; la IP de
un runner compartido las tiene agotadas casi siempre, y el resultado es un 403 que rompió la suite
en la primera ejecución del pipeline sobre un clon limpio.
**Opciones:**
- (a) dejarlo sin autenticar y convivir con un CI que falla de forma intermitente;
- (b) fijar la versión del depurador y del servidor de respaldo para no preguntar a la API;
- (c) autenticar la consulta cuando haya un token en el entorno.
**Decisión:** (c), con el alcance acotado en un módulo puro (`src/shared/github-api.ts`).
**Consecuencias:** autenticar sube el límite a 5 000 peticiones/hora, pero mete una credencial en el
proceso, así que el alcance es la parte importante de la decisión y no un detalle de implementación:

- El token se adjunta **sólo** si el host es exactamente `api.github.com` y el protocolo es HTTPS.
  La comparación es del `hostname` completo: `api.github.com.malo.dev` **contiene** el host bueno y
  no lo es, y un subdominio tampoco hereda la credencial.
- No lo llevan la descarga del artefacto (`objects.githubusercontent.com`), ni el feed de Azure donde
  se publica Roslyn, ni el registro de extensiones. Son las peticiones que más pesan y ninguna
  necesita credencial.
- Se lee de `GITHUB_TOKEN` o `GH_TOKEN` y **en un único archivo de todo `src/`**, con una prueba
  estructural que lo vigila: si el token se pudiera leer desde cualquier módulo, la garantía
  dependería de que nadie se despiste, que no es una garantía.
- Fuera de CI no suele haber ninguna de las dos variables, y ése es el camino normal: sin token, el
  comportamiento es idéntico al anterior.
- La opción (b) se descartó porque el problema no es la elección de versión —eso ya se resolvió para
  Roslyn en la ADR-040— sino la consulta en sí: incluso fijando la versión hay que resolver la URL
  del artefacto, y eso pasa por la API.
---

### ADR-051 — En el proceso principal, nada de CPU síncrona sobre búferes grandes
**Fecha:** 2026-08-24
**Contexto:** Instalar una extensión de Open VSX daba tirones severos y ratos de ventana congelada.
La red y el disco ya eran asíncronos; lo que bloqueaba eran las dos operaciones de CPU que hay en
medio: `inflateRawSync` por cada archivo del `.vsix` y `createHash().update(buffer)` por cada archivo
extraído y por el paquete entero. Las dos trabajan en C++, y por eso es fácil darlas por gratuitas,
pero lo hacen **en el hilo que llama** — en Electron, el mismo que repinta la ventana y atiende el
IPC del renderer.
**Opciones:**
- (a) dejarlo y avisar con un spinner;
- (b) mover la instalación a un `worker_thread`;
- (c) usar las variantes asíncronas que ya ofrecen `zlib` y `crypto`, y trocear lo que no la tenga.
**Decisión:** (c).
**Consecuencias:**

- `readEntryAsync` usa `inflateRaw`, que va al pool de libuv: el trabajo sale del hilo principal y,
  de propina, cada `await` de la extracción es una vuelta del bucle de eventos.
- `sha256Async` trocea en bloques de 4 MiB y cede con `setImmediate` entre bloques. `hash.update()`
  no tiene variante asíncrona útil aquí, así que lo que se controla es la duración de cada bloque.
- La variante síncrona de `readEntry` se conserva **para leer una entrada suelta y pequeña** (el
  `extension.vsixmanifest` de un `.vsix` son unos kilobytes); una prueba estructural exige que la
  extracción no vuelva a usarla.
- Se va también `existsSync` de los dos instaladores: la ausencia de un archivo la resuelve igual de
  bien el `readFile` que venía después.
- (b) se descartó por desproporcionada: un worker obliga a serializar búferes de cientos de MB o a
  compartir memoria, y el problema se resuelve entero sin salir del hilo.
- Lo que **no** cambia: el manifiesto anota exactamente los mismos tamaños y hashes, que es de lo
  que depende que una copia corrupta se detecte (ADR-041). Hay una prueba que lo compara contra el
  cálculo síncrono.
- **Dónde importa de verdad, medido:** un `.vsix` corriente son muchos archivos pequeños y entre
  ellos ya había un `await writeFile` que cedía el bucle, así que el camino síncrono tampoco se nota
  ahí (1-2 ms de peor respuesta del proceso principal, igual que el asíncrono). El bloque largo lo
  producen los **archivos grandes**: sobre el `Microsoft.CodeAnalysis.CSharp.dll` real de Roslyn
  (18,3 MB), un solo `inflateRawSync` son 50 ms de hilo principal parado, y el `sha256` del paquete
  entero otros 51 ms por cada 96 MB — en una máquina con SHA-NI. La decisión no cambia por eso: un
  bloque de 50 ms repetido por cada archivo grande de un paquete de 250 MB es exactamente el tirón
  que se describía, y no hay motivo para pagarlo.

---

### ADR-052 — El repintado devuelve el foco; no se deja de repintar
**Fecha:** 2026-08-24
**Contexto:** Al hacer una pausa breve escribiendo en la búsqueda de NuGet o en la de extensiones, el
cursor desaparecía y las letras siguientes se perdían. La causa no es el rebote —hace falta— sino lo
que dispara: la vista vacía su contenedor y lo reconstruye, y el `<input>` enfocado es uno de los
nodos que se destruyen. En el panel de extensiones pasa tres veces por búsqueda.
**Opciones:**
- (a) repintar sólo la lista de resultados y dejar la barra de búsqueda fuera del repintado;
- (b) introducir reconciliación de DOM (un mini DOM virtual) en las vistas;
- (c) conservar y restaurar el foco alrededor del repintado.
**Decisión:** (c), con las reglas en un módulo puro (`src/renderer/focus-guard.ts`).
**Consecuencias:**

- Cada campo que quiera sobrevivir se marca con `data-focus-key`, y el repintado va envuelto en
  `repaintPreservingFocus`. Sólo se restaura si el foco estaba **dentro** del contenedor repintado:
  un repintado del panel no puede robarle el cursor a la terminal.
- **El valor no se restaura nunca**: lo pinta la vista desde su estado, que es la verdad. La foto
  sólo manda sobre la selección, y sólo mientras el texto no haya cambiado; si cambió, el cursor se
  va al final.
- (a) es más quirúrgico pero no generaliza: hay varios paneles con caja de búsqueda y habría que
  inventar la excepción en cada uno, y cualquier vista futura repetiría el fallo.
- (b) es la solución "de libro" y es la que no encaja aquí: el renderer construye el DOM a mano a
  propósito (nada de `innerHTML`), y meter un reconciliador cambiaría cómo se escribe toda la
  interfaz para arreglar un problema de dos paneles.

---

### ADR-053 — El estado de sólo lectura del editor se recalcula en cada punto de control
**Fecha:** 2026-08-24
**Contexto:** Se investigó un síntoma reproducible a ratos: el editor dejaba de admitir texto nuevo
pero seguía permitiendo borrar, y sólo se arreglaba reiniciando. Al buscar el culpable no apareció:
**hoy ningún camino enciende `readOnly` en el editor de código** —sólo lo declara el editor de
diferencias, y ahí es por diseño (ADR-021)—. Lo que sí es cierto es la propiedad que hace posible el
fallo: `readOnly` en Monaco es pegajoso y nadie lo revisaba nunca. Basta con que algún camino
asíncrono lo encienda y muera antes de apagarlo.
**Opciones:**
- (a) no tocar nada, porque hoy no hay ningún camino que lo encienda;
- (b) envolver en `try/finally` los caminos asíncronos que existen hoy;
- (c) hacer que el valor deje de ser una suposición y se recalcule desde una regla única.
**Decisión:** (c), y (b) como parte de ella.
**Consecuencias:**

- `src/renderer/editor-state.ts` es la única regla, pura y probada. Sólo dos cosas hacen el editor de
  sólo lectura, y las dos son estructurales: que no haya archivo abierto y que se esté enseñando una
  comparación.
- **Nada asíncrono bloquea la escritura**, y es deliberado: formatear al guardar tarda lo que tarde
  el servidor de lenguaje, y prohibir teclear durante ese rato sería un remedio peor que la
  enfermedad. Las operaciones en vuelo se cuentan sólo para que su `finally` sea un punto de
  recálculo.
- `refreshEditability()` se llama al montar, al abrir, al activar, al cerrar y al entrar y salir de
  una comparación. Un bloqueo que se cuele dura, como mucho, hasta el siguiente cambio de pestaña.
- Monaco dice **por qué** no se puede escribir (`readOnlyMessage`). Un editor que no acepta lo que se
  teclea y no dice nada es exactamente el fallo que se estaba investigando.
- (a) se descartó porque el coste de la garantía es una función pura y seis llamadas, y el coste de
  no tenerla es una sesión de trabajo perdida por un fallo que no deja rastro en ningún registro.

---

### ADR-054 — La barra de actividad se ordena a gusto, y se pulsa por identificador
**Fecha:** 2026-08-24
**Contexto:** El orden de la barra estaba escrito a mano en `renderActivityBar` y los modos de
diagnóstico `--ui=` pulsaban los iconos por índice posicional dentro de `.activity-item`. Eso se
rompió en silencio dos veces al añadir una herramienta (Fase 15 y Fase 17), las dos anotadas en
`CLAUDE.md` como trampa conocida.
**Opciones:**
- (a) un orden fijo mejor pensado;
- (b) reordenar desde una lista en Ajustes;
- (c) reordenar arrastrando los propios iconos, con el orden en las preferencias.
**Decisión:** (c).
**Consecuencias:**

- El orden se guarda como lista de identificadores en `activityBar.order`, nunca como posiciones, y
  `normalizeActivityOrder` lo trata como una sugerencia: descarta lo desconocido y lo repetido, y
  completa al final lo que falte. Un archivo escrito por una versión anterior tiene que dar una
  barra completa, no una barra a la que le falta un icono.
- **"Ajustes" no se mueve**: vive bajo el separador, al fondo, que es donde se busca en cualquier
  editor. Dejarlo subir sólo serviría para que alguien lo perdiera de vista.
- Los `--ui=` pasan a `[data-tool-id=…]`. Con un orden que cambia el usuario, la posición ya no
  significa nada; una prueba estructural vigila que no vuelva ningún índice.
- Ajustes no tiene una lista para reordenar —se reordena donde se ve el resultado— pero sí la salida
  de emergencia: "Restaurar el orden", que sólo aparece cuando hay algo que deshacer.
- (b) se descartó porque duplica la barra en un sitio donde no está: dos representaciones del mismo
  orden, y la de Ajustes siempre peor.

---

### ADR-055 — La frontera de la terminal es qué se ejecuta, no desde dónde
**Fecha:** 2026-08-24
**Contexto:** La terminal integrada lanzaba cada línea con el directorio de la solución como `cwd` y
no llevaba la cuenta de dónde estaba el usuario. `cd` ni siquiera llegaba a intentarse: se buscaba un
programa llamado `cd`, que no existe porque es una orden del intérprete, y el error hablaba de la
lista de programas permitidos. El resultado era una terminal en la que no se podía navegar, y en un
IDE de .NET eso duele en cuanto hay que mirar otra solución, otra unidad o la carpeta de al lado.

Al arreglarlo aparece la pregunta de verdad: **¿hasta dónde puede navegar el usuario?**
**Opciones:**
- (a) permitir `cd` sólo dentro del workspace abierto;
- (b) permitir `cd` a cualquier sitio, manteniendo intacta la lista blanca de programas;
- (c) permitir `cd` a cualquier sitio y además ampliar la lista blanca, "ya que estamos".
**Decisión:** (b).
**Consecuencias:**

- El `cwd` de la terminal **no** pasa por `assertInsideWorkspace`. Ese guardián existe para las
  rutas que llegan del renderer a los canales de archivos —donde el origen puede ser cualquier cosa
  que el IDE haya leído— y no para una carpeta que el usuario acaba de escribir a mano.
- (a) se descartó porque no impide nada: `dotnet build ..\otra\App.sln` ya cruzaba esa línea sin
  cambiar de directorio, y el mismo `git` que se puede lanzar dentro del workspace acepta `-C`. Una
  frontera que sólo detiene la forma cómoda de hacer algo no es una frontera, es una molestia.
- (c) se descartó sin discusión: la lista blanca es lo que de verdad acota la superficie (ADR-004), y
  relajarla porque se ha tocado otra cosa es exactamente cómo se pierden las garantías.
- Lo que se refuerza a cambio: dos pruebas estructurales nuevas exigen que el ejecutor siga con
  `shell: false`, con el argv como array y con la comprobación contra la lista blanca. Si alguien
  relaja el `cwd` un poco más en el futuro, no se llevará lo demás por delante en la misma revisión.
- El destino se comprueba antes de aceptarlo (existe y es un directorio) y el error dice la **ruta ya
  resuelta**: "no existe `src`" no ayuda a nadie; "no existe `C:\repos\Acme\src`" se comprueba de un
  vistazo.
- `cd` a secas **no** hace lo que hace cmd (imprimir) ni lo que hace POSIX (ir al hogar): vuelve a la
  raíz de la solución. Dentro de un IDE es lo que uno quiere el 99 % de las veces, y es lo que hace
  que la orden sirva para algo en vez de ser una curiosidad de plataforma. Sin solución abierta, al
  hogar.

---

### ADR-056 — El contenido del menú es un dato puro, no código dentro de `menu.ts`
**Fecha:** 2026-08-24
**Contexto:** La barra de menú nativa vivía entera dentro de `src/main/menu.ts`, que importa
`electron`. Eso significa que no se podía cargar en una prueba, y por tanto que las tres formas en
que un menú se rompe **en silencio** no las veía nadie: una entrada que manda un comando que el
renderer no registra (se pulsa y no pasa absolutamente nada, porque `runCommandById` busca en la
paleta y sale sin decir nada), dos entradas peleándose por el mismo acelerador (Electron registra
las dos y gana una, sin que esté escrito cuál), y funcionalidades que existen en la paleta y no
llegan al menú — había unos 60 comandos y el menú enseñaba unos 45.
**Opciones:**
- (a) dejarlo y revisarlo a ojo abriendo los menús;
- (b) probar `menu.ts` con un doble de `electron`;
- (c) sacar el contenido a un módulo puro y dejar en `menu.ts` sólo la traducción.
**Decisión:** (c), más un modo de diagnóstico `--menu-dump` para lo que el dato no puede saber.
**Consecuencias:**

- `src/shared/menu-template.ts` describe la barra como datos (`command`, `role`, `link`,
  `separator`, `recents`) y `menu.ts` la traduce. La prueba mira el dato.
- (b) se descartó: un doble de `electron` comprobaría que el doble se llama bien, no que Electron
  acepte lo que se le manda. Es justo lo que no interesa saber.
- **Lo que el dato no puede saber tiene su propio modo de diagnóstico.** Un `role` inválido o un
  acelerador que Electron no sepa parsear sólo fallan en ejecución, así que `--menu-dump` imprime la
  barra **ya construida** y sale. No es un adorno: encontró dos choques de acelerador reales que la
  prueba pura no podía ver.
- **Los `role` traen acelerador aunque no lo declaren**, y ésa era la mitad invisible del problema:
  `togglefullscreen` se quedaba `F11` —que en un IDE es "paso a paso por instrucciones"— y `close`
  se quedaba `Ctrl+W`, que es cerrar pestaña. Se añade `ROLE_ACCELERATORS` con lo que Electron pone
  por su cuenta, la comprobación de choques lo tiene en cuenta, y hay una prueba que exige que
  ningún `role` nuevo entre sin apuntar el suyo. Con eso, el tercer choque (el mismo `Ctrl+W` en el
  menú Archivo de macOS) lo encontró ya la prueba.
- Donde hay conflicto entre la convención de Electron y la de Visual Studio, **gana Visual Studio**:
  es el IDE del que viene quien usa esto. `F11` es paso a paso; pantalla completa se va a
  `Alt+Shift+Enter`, que además es el atajo que usa el propio Visual Studio.
- El menú se **reinstala** al abrir una solución. Un menú de Electron es estático una vez puesto, y
  "Soluciones recientes" es lo único que cambia; reconstruir unas decenas de entradas es barato y es
  la única forma de que no mienta.

---

### ADR-057 — La búsqueda recorre el workspace, y quién dice cuál es el workspace no es el renderer
**Fecha:** 2026-08-24
**Contexto:** Buscar dentro de los archivos es la primera funcionalidad que **lee el disco en bucle
a petición del renderer**. Todo lo anterior que tocaba archivos abría uno concreto, con su ruta
validada por `assertInsideWorkspace`. Aquí no hay una ruta: hay un árbol entero, y la pregunta
evidente es quién decide de dónde cuelga.
**Opciones:**
- (a) que el renderer mande la raíz y validarla con `assertInsideWorkspace`;
- (b) que el proceso principal la tome de `getWorkspaceRoot()` y el canal no acepte ninguna ruta;
- (c) permitir buscar en una carpeta arbitraria elegida con un diálogo.
**Decisión:** (b).
**Consecuencias:**

- El canal `search:in-files` **no tiene ninguna ruta que validar**, que es una garantía más fuerte
  que validarla bien: no hay forma de pedirle que recorra `C:\Windows` ni de escaparse con `..`,
  porque no hay parámetro por donde intentarlo. Lo demás que llega del renderer —consulta, banderas,
  globs y topes— pasa entero por `coerceSearchOptions`, y los topes están acotados: un renderer
  comprometido no puede pedir un millón de resultados para agotar la memoria.
- (a) se descartó porque no aporta nada: el renderer no conoce ninguna raíz que el proceso principal
  no conozca ya, así que aceptarla sólo añade una superficie que hay que validar en cada revisión.
- (c) se descartó por ahora. Buscar en una carpeta fuera de la solución abierta es una petición
  razonable, pero el camino honesto para eso es **abrir esa carpeta**, que es lo que ya hace el IDE
  y lo que además deja el explorador, el LSP y la terminal diciendo lo mismo.
- Sin solución abierta el canal contesta un resumen vacío con su motivo, no un error: no tener nada
  abierto es un estado normal. Y cerrar la solución cancela la búsqueda en marcha, que si no seguiría
  leyendo archivos de un workspace que ya no lo es.
- La terminal fue en dirección contraria (ADR-055: el `cwd` **no** se ata al workspace) y no es una
  contradicción: allí quien navega es una persona escribiendo `cd`, y lo que acota la superficie es
  la lista blanca de programas. Aquí quien recorre es código, en bucle, sin que nadie mire.
- El recorrido no usa nada síncrono, por la misma razón que el ADR-051: en Electron, el hilo que lee
  el disco es el que repinta la ventana y atiende el IPC del renderer. Hay una prueba estructural que
  se pone en rojo si vuelve a aparecer un `readFileSync` ahí dentro, porque es de lo más fácil de
  colar en una revisión: compila, funciona y sólo se nota con una solución grande delante.

---

### ADR-058 — El JSON que el IDE no escribe se lee con tolerancia a la marca de orden de bytes
**Fecha:** 2026-08-25
**Contexto:** una Web API generada por el propio DotForge arrancaba en el puerto 5000, por HTTP, en
Production y sin *static web assets*, con el IDE diciendo que estaba lanzando el perfil `https`. Tres
causas encadenadas, y ninguna de las tres da un error que se vea:

1. El `launchSettings.json` guardado por Visual Studio empieza por `EF BB BF`. `JSON.parse` la
   rechaza en la posición 0 y `readLaunchEnvironment` devolvía cero variables con un aviso que sólo
   aparece en la salida del depurador.
2. Cuando sí se leía, `selectProfile` cogía "el primero declarado" si no había uno con el nombre del
   proyecto. Las plantillas del SDK declaran `http` **antes** que `https`.
3. Y `dotnet run` sin `--launch-profile` hace lo mismo por su cuenta: aplica el primero del archivo,
   sin importar cuál hubiera resuelto el IDE.

**Opciones:**
- (a) quitar el BOM sólo en `launch-settings.ts`, que es donde se vio;
- (b) un lector compartido (`parseJsonText`) para **todo** JSON que el IDE no haya escrito él;
- (c) leer los archivos como `latin1` y convertir, o normalizar la codificación al abrir el proyecto.

**Decisión:** (b), más la prioridad de HTTPS y `--launch-profile` explícito.
**Consecuencias:**

- El BOM no es un problema de `launchSettings.json`: es un problema de **cualquier archivo que
  escriba otra herramienta**. `appsettings.json`, el `package.json` de una extensión, un
  `.vsix` de un publicador cualquiera. Arreglarlo en un sitio garantiza que vuelva a aparecer en
  otro dentro de seis meses, así que se arregla en el único sitio por el que pasan todos.
- **Sólo la marca del principio.** Un U+FEFF en mitad del archivo es un carácter de contenido —un
  espacio de ancho cero— y borrarlo cambiaría el valor de una cadena. `stripBom` mira la posición 0
  y nada más.
- Se sigue lanzando `SyntaxError` con cualquier otro error de formato. Lo que se arregla es una
  diferencia de codificación, no una invitación a tragarse un archivo roto: (c) se descartó por eso
  —convertir a ciegas oculta los archivos que de verdad están mal— y porque reescribir el archivo
  del usuario para "normalizarlo" es meter mano en su repositorio sin que lo haya pedido.
- **HTTPS gana el desempate, el nombre del proyecto gana sobre HTTPS.** Quien llama a su perfil como
  el proyecto está diciendo cuál quiere; entre los demás, arrancar en claro deja el certificado de
  desarrollo sin usar y rompe a cualquier cliente que apunte al puerto seguro. Entre varios HTTPS
  sigue mandando el orden del archivo, que es el criterio del SDK.
- **El perfil se nombra siempre, no sólo cuando alguien lo pide.** El fallo era de omisión: mientras
  la bandera no esté, la CLI y el IDE pueden estar hablando de perfiles distintos sin que nada lo
  diga. `launchProfileArgs` la acota a `run` y `watch` —los demás verbos la rechazan— y el nombre
  viaja como argumento suelto del array, porque un perfil puede llamarse "IIS Express".
- Lo resuelve el **proceso principal**, no el renderer: el archivo está en el disco y el renderer no
  conoce `launchSettings.json`. Misma regla que la verbosidad de la CLI y que el prompt del
  asistente (ADR-016).

---

### ADR-059 — Pseudoterminales con node-pty: se rompe el "sin dependencias nativas", pero no lo que protegía
**Fecha:** 2026-08-25
**Contexto:** la terminal integrada no tenía PTY por una decisión explícita de la Fase 9: `node-pty`
es nativa, y el proyecto se había comprometido a no tener ninguna para que el empaquetado fuera
reproducible y no hiciera falta compilar nada en la máquina del usuario. A cambio, la terminal
ejecutaba comandos concretos de una lista blanca y enseñaba su salida.

Eso cubre el flujo de .NET y no cubre nada interactivo: ni un REPL, ni `dotnet user-secrets set` con
su aviso, ni `git rebase -i`, ni el prompt de PowerShell con sus colores, ni `Ctrl+C`. Para
cualquiera de esas cosas hay que salir del IDE, que es justo lo que un IDE existe para evitar.

**Opciones:**
- (a) dejarlo como está y asumir que la terminal del IDE es de segunda;
- (b) `node-pty` como dependencia normal, con paso de rebuild por plataforma;
- (c) `node-pty` como `optionalDependency`, cargada tarde y con degradación explícita, conviviendo
  con la terminal asistida;
- (d) escribir un PTY propio, o lanzar el intérprete con tuberías fingiendo una consola.

**Decisión:** (c).
**Consecuencias:**

- **El compromiso que importaba sigue en pie.** Lo inaceptable de una dependencia nativa no era el
  `.node`: era el paso de rebuild —node-gyp, Visual Studio Build Tools, un artefacto distinto por
  versión de Electron— y que el empaquetado dejara de ser reproducible. `node-pty` publica desde la
  1.1 los binarios ya compilados dentro del propio paquete y son **Node-API**, que es ABI estable,
  así que valen para Electron sin `electron-rebuild`. La prueba de empaquetado que prohibía la
  dependencia se reescribe para exigir lo que de verdad se quería: ninguna dependencia **que haya
  que compilar**, y que ésta venga con binario para esta plataforma.
- **Pero a electron-builder hay que decírselo.** *(Añadido tras el fallo de la Iteración 31.)* No
  comprueba si el módulo trae binarios: ve una dependencia nativa y lanza `@electron/rebuild`, que
  llama a node-gyp y exige Visual Studio. En un equipo sin las Build Tools el empaquetado muere con
  `Could not find any Visual Studio installation to use` **aunque el `.node` que se va a distribuir
  ya esté ahí y funcione**. Se apaga con `npmRebuild: false`, y hay una prueba que lo exige: es la
  clase de línea que alguien quita "porque parece que no hace nada".
- **Es opcional, y la ausencia es un valor.** Se carga con `createRequire` dentro de un `try`, la
  primera vez que hace falta. Sin binario —o con npm 11 bloqueando los scripts de instalación, que
  es el caso normal— los perfiles de PTY se ofrecen **atenuados y con el motivo escrito** y la
  terminal asistida sigue funcionando. Misma regla que con Docker apagado (ADR-033): que falte una
  fuente no puede vaciar el panel.
- **La asistida no se sustituye: deja de ser la única.** Sigue siendo la única que sugiere
  subcomandos y ramas mientras se escribe —conoce la línea entera, cosa que un PTY no—, y la única
  que funciona en una instalación sin binario. Es un perfil más del menú, con su ventaja dicha ahí
  mismo.
- **Dentro de un PTY no hay lista blanca de programas, y eso es deliberado.** Una terminal que sólo
  deja ejecutar doce cosas no es una terminal; quien abre PowerShell está pidiendo PowerShell. Lo
  que sí queda acotado, y por escrito en `tests/security/hardening.test.mjs`, es **quién** abre una
  sesión y con qué: el perfil llega como identificador y pasa por `coerceProfileId`, que sólo puede
  devolver uno del catálogo, así que no hay forma de pedirle al canal que lance un programa
  arbitrario; el `cwd` **no llega del renderer** (se toma de la sesión de la terminal, como la raíz
  de la búsqueda en el ADR-057); y hay tope de sesiones y tope por escritura.
- (d) se descartó sin dudar: un pseudoterminal es una primitiva del sistema operativo, y ConPTY en
  Windows no se emula con tuberías. Lo que se consigue fingiendo es exactamente lo que ya había.
- **Cerrar la pestaña es cerrar la sesión**, y cerrar el IDE se lleva todas. Un intérprete
  invisible que sigue vivo con un `dotnet watch` dentro ocupando un puerto es de los estados más
  desconcertantes que puede dejar un programa.
- **La pestaña no se cierra sola cuando el intérprete termina.** Si el `exit` fue un error, lo
  último que escribió es lo único que lo explica.
- xterm.js **no se bundlea**, por la misma razón que Monaco: son 500 KB que se sirven mejor como
  archivo del vendor, y hay una prueba que vigila que el bundle del renderer siga siendo un orden de
  magnitud más pequeño que lo que dice no incrustar.

---

### ADR-060 — La release la publica la CI con `gh`, y el tag manda sobre lo que se publica
**Fecha:** 2026-08-26
**Contexto:** El sistema de actualizaciones existe desde la v2.1.0 y **nunca ha tenido de dónde
actualizarse**. El workflow construía los artefactos y los dejaba como *artifacts* del run: caducan
a los 90 días, no se ven desde fuera y no aparecen en `/repos/sfedev/IDE-DOTNET/releases`, que es lo
único que el IDE consulta. El feed respondía 200 con cero elementos, así que `update:check` decía
"estás en la última versión" y tenía razón: no había ninguna publicada. La auditoría de la
Iteración 31 lo dejó anotado como el bloqueante del siguiente ciclo.
**Opciones:**
- (a) `softprops/action-gh-release`, que es lo que usa casi todo el mundo;
- (b) la CLI `gh`, que viene instalada en los runners;
- (c) `electron-updater` con su `latest.yml` y su canal de publicación;
- (d) publicar a mano desde la web y que la CI sólo construya.

**Decisión:** (b), con el paso de publicación en un job aparte.
**Consecuencias:**

- **Publicar es la operación con más permisos del repositorio**, y (a) mete una acción de terceros
  corriendo con el token de escritura. Para que ese `uses:` significara algo habría que fijarlo por
  SHA y volver a auditarlo en cada subida. `gh` ya está en el runner y hace exactamente lo mismo.
  Hay una prueba que recorre los `uses:` del job de publicación y exige que todos sean `actions/*`.
- **El permiso vive donde se usa.** El workflow declara `contents: read` y sólo el job `publish`
  sube a `write`. Los jobs que compilan y prueban no necesitan poder escribir releases, y con el
  permiso a nivel de workflow lo tendrían los tres.
- **El tag y `package.json` tienen que decir la misma versión, y la CI se para si no.** Es la
  comprobación que evita el peor fallo de todo el ciclo: el artefacto lleva la versión de
  `package.json` incrustada en el nombre y quien decide si hay actualización es el **tag**.
  Publicar un `v2.6.0` con binarios `2.5.0` deja al IDE ofreciendo la 2.6.0, instalando un 2.5.0 y
  encontrándose al arrancar con una instalación pendiente que sigue siendo "más nueva" que la que
  corre (`initialize` sólo descarta lo pendiente si **no** es posterior): se reinstalaría en cada
  cierre, indefinidamente. No hay nada que el cliente pueda hacer contra eso, así que se corta en
  el único sitio donde se puede.
- **Los tres disparos convergen.** Un tag empujado, una release creada desde la web y un disparo
  manual acaban en el mismo par crear-o-completar más `upload --clobber`, que además hace el paso
  idempotente: relanzar el workflow reemplaza los artefactos en vez de fallar por duplicado. El
  disparo por `release: published` no se muerde la cola porque una release creada con el
  `GITHUB_TOKEN` por defecto no dispara workflows nuevos — es una garantía de GitHub, y conviene
  saberla antes de cambiar ese token por uno personal.
- **(c) sigue descartado por lo mismo que en el ADR-045:** exige artefactos firmados, y aquí no hay
  certificado. (d) es lo que había de facto y es justo lo que ha fallado durante nueve versiones:
  un paso manual que hay que acordarse de dar no se da.
- **Un borrador no está publicado.** El paso que verifica el feed se salta cuando se pide borrador,
  porque un borrador nunca aparece ahí: exigirlo haría fallar siempre la publicación en borrador, y
  por el motivo equivocado.
- **Publicar no es lo mismo que estar publicado.** El último paso pregunta a la API pública si la
  release aparece con al menos un artefacto. Es la diferencia entre comprobar la configuración y
  comprobar el resultado, que es la lección de la Iteración 31 con el empaquetado.

---

### ADR-061 — Las pestañas de terminal se restauran, y el archivo no puede colar un directorio
**Fecha:** 2026-08-26
**Contexto:** La Fase 21 dejó esto sin hacer a propósito, con un argumento que sigue siendo cierto:
**restaurar una terminal es, como mucho, volver a abrirla vacía en el mismo directorio**. No vuelve
el histórico, ni el proceso que estuviera corriendo, ni la línea a medio escribir. Y hay una razón
técnica de fondo: el directorio *actual* de un intérprete detrás de un ConPTY no se puede consultar
—el `cd` lo gobierna él—, así que lo único que se sabe de una pestaña es con qué perfil y en qué
directorio **nació**. Lo que se pide de verdad, aun así, es real: al reabrir una solución uno espera
encontrarse el panel como lo dejó.
**Opciones:**
- (a) no hacerlo, como hasta ahora;
- (b) restaurar la disposición: perfiles, orden, cuál estaba delante y el directorio de la sesión;
- (c) además, intentar recuperar el histórico de cada pestaña (grabar la salida y reproducirla);
- (d) restaurar también al cambiar de solución con el IDE abierto, cerrando lo que hubiera.

**Decisión:** (b), con un ajuste para apagarlo.
**Consecuencias:**

- **Se restaura la disposición, y se dice que es sólo eso.** El ajuste de Ajustes lleva la letra
  pequeña escrita al lado: "no recupera lo que hubiera escrito ni lo que estuviera corriendo". El
  argumento de la Fase 21 no se ha refutado, se ha convertido en un interruptor: a quien tenía tres
  PowerShell a medias, reabrirle tres PowerShell que no son los suyos le sobra, y ahora puede
  apagarlo. Apagarlo no borra lo guardado.
- **(c) se descartó.** Reproducir la salida de un intérprete muerto pinta una sesión que parece viva
  y no lo está: el prompt de arriba responde a un proceso que ya no existe. Es peor que un panel
  vacío, porque miente.
- **(d) también.** Cambiar de solución con terminales abiertas **no** las cierra: dentro de una
  puede haber un `dotnet watch` corriendo, y llevárselo por delante para reabrir una pestaña vacía
  es un intercambio malísimo. Sólo se restaura sobre un panel intacto.
- **El `cwd` no llega del renderer, y ésa es la parte de seguridad.** Era la puerta de atrás
  evidente al ADR-059: si el renderer mandara el directorio al guardar, ese valor volvería del
  disco y sería el directorio de un intérprete real, sin haber tocado `terminal:create`. El canal de
  guardado acepta identificadores de perfil y un índice, y nada más; el directorio lo pone el
  proceso principal desde la sesión de la terminal y la clave la pone `getWorkspaceRoot()`. Hay una
  prueba de seguridad por cada mitad.
- **Lo guardado se sanea al leerlo**, no sólo al recibirlo: el archivo lo escribe una versión del
  IDE y lo lee otra, y el identificador acaba decidiendo qué intérprete se lanza. Pasa por el mismo
  `coerceProfileId` que ya trata un perfil desconocido como una migración y no como un error.
- **Se anota en cada cambio, no al cerrar.** Abrir otra solución cambia la clave con la que se
  guarda, así que "guardar al salir" obligaría a capturar el estado justo antes de ese cambio, que
  es una carrera esperando a pasar. Anotando en el momento, la entrada siempre está al día y cambiar
  de solución no tiene que hacer nada.
- **Una pestaña que aquí no se puede abrir se salta y se dice.** Sin `node-pty`, una disposición de
  tres PowerShell no puede dejar tres pestañas muertas con un mensaje dentro: se abre lo que se
  puede y se avisa de cuántas se han quedado fuera y por qué (ADR-033, otra vez).

---

### ADR-062 — Claude Code es un intérprete del catálogo, y lo declarativo de un `.vsix` por fin se consume
**Fecha:** 2026-08-27
**Contexto:** Dos preguntas que resultaron ser la misma. La primera: cómo usar la extensión de
Claude Code para VS Code dentro de DotForge. Se auditó lo que necesita —96 símbolos distintos de la
API de `vscode`, concentrados en `workspace`, `window`, `commands` y `Uri`— y lo que decide es que
**su interfaz es un webview**: `createWebviewPanel`, `registerWebviewViewProvider`,
`registerWebviewPanelSerializer`. Un webview es HTML y JavaScript de un tercero dentro de la ventana,
y eso choca de frente con la CSP del renderer y con la regla de que aquí no se inyecta marcado — ni
siquiera para los iconos (ADR-049).

La segunda salió de la misma auditoría: el IDE **no consumía nada** de las extensiones instaladas.
El ADR-048 decía que las contribuciones declarativas "sirven aquí" y que la lista crecería cuando el
IDE supiera consumirlas; entretanto, `defineThemes()` sólo definía los dos temas propios y nadie
leía la carpeta de extensiones salvo el instalador. La ficha decía la verdad sobre lo que *no*
funcionaba y una promesa sobre lo que sí.
**Opciones:**
- (a) escribir un host de extensiones con webviews, para ejecutar la extensión tal cual;
- (b) host mínimo sin webviews, que dejaría la extensión de Claude Code a medias;
- (c) integrar la **CLI** como un perfil más de la terminal, y aparte cumplir lo declarativo;
- (d) no hacer nada y seguir instalando extensiones sin consumirlas.

**Decisión:** (c), las dos mitades.
**Consecuencias:**

- **La CLI no necesita un host: necesita una terminal de verdad, y eso existe desde la v2.5.0.**
  Claude Code pasa a ser un perfil del catálogo, con su comando, su atajo y su pestaña. El coste es
  una tarde en vez de un trimestre, y lo que se pierde frente a la extensión —el panel lateral, las
  diferencias dentro del editor— es justo lo que exigía el webview.
- **Un perfil puede tener varias formas de lanzarse, todas del catálogo.** `claude` se instala de
  tres maneras y ninguna es la canónica: el instalador nativo deja un ejecutable, `npm install -g`
  deja un `.cmd` en Windows, y `npx` funciona sin instalar nada. Elegir una sola declararía no
  disponible a quien tenga cualquiera de las otras dos. La garantía del ADR-059 no cambia: el
  renderer manda un identificador y nada más; las alternativas son una lista cerrada escrita en el
  catálogo, y hay una prueba de seguridad que lo exige.
- **Lo que se lanza es la ruta resuelta, no el nombre.** En Windows, `CreateProcess` busca por
  `PATH` pero sólo prueba `.exe`: `npx` se encuentra al comprobar y **falla al lanzarse**. Aparece
  como "Cannot create process, error code: 2", que no menciona ni el programa ni la extensión.
- **En la terminal asistida, `claude` es una orden del intérprete**, como `cd` y `pwd` (ADR-055).
  Ahí no hay pseudoterminal y Claude Code es una interfaz de pantalla completa: intentarlo y fallar
  —o rechazarlo por la lista blanca, que hablaría de permisos— es peor que llevarlo a su pestaña.
- **Y lo declarativo se consume de verdad.** Temas y fragmentos de los `.vsix` instalados, leídos,
  convertidos y aplicados. Es el ADR-048 cumplido, no ampliado: lo que se ejecuta sigue siendo nada.
- **Un tema de extensión colorea el editor, no la ventana.** No sabe nada de la barra de actividad
  ni del panel, que se pintan con los tokens de `theme.css`. El resto del IDE usa el tema propio que
  declare su `uiTheme`, y el ajuste lo dice con esas palabras: la alternativa era fingir que reviste
  la ventana entera y que el usuario descubriera que no.
- **Toda ruta del manifiesto se valida contra la carpeta de la extensión.** `contributes` es JSON
  escrito por un tercero, viene dentro de un paquete descargado de un registro público, y su `path`
  acaba en un `readFile`. Mismo cuidado que ya se tiene con el nombre de la carpeta al instalar
  (ADR-047).
- (a) sigue sobre la mesa y ahora se sabe lo que cuesta: el host y el modelo de objetos son trabajo
  mecánico; el webview es una decisión de seguridad que merece su propio ADR el día que se tome.

---


### ADR-064 — Publicar tiene canal propio, y las banderas que dependen del RID no se emiten sin él
**Fecha:** 2026-08-27
**Contexto:** `dotnet publish` es el primer verbo del SDK que el IDE lanza con **opciones que elige
el usuario en un formulario**. Eso abre dos frentes a la vez: una superficie nueva por la que se
compone la línea de comandos de un proceso hijo, y un conjunto de banderas que dependen unas de
otras de una forma que el propio SDK no siempre denuncia.

`-p:PublishSingleFile=true` sin `-r` no produce un archivo único: según la versión del SDK se
ignora o falla, y en el mejor caso se publica un directorio normal. Quien había marcado la casilla
se queda mirando una carpeta con doscientos archivos, sin ningún error que lo explique.
**Opciones:**
- (a) hacer `publish` un `DotnetTaskKind` más y mandar las banderas en `extraArgs`;
- (b) canal propio con las opciones como **datos**, y los argumentos compuestos en el proceso
  principal por una función pura.

**Decisión:** (b).
**Consecuencias:**

- **(a) habría dejado un camino por el que el renderer escribe línea de comandos.** `dotnet:run-task`
  ya acepta `extraArgs` para lo que lo necesita, y con `publish` dentro de `TASK_KINDS` cualquiera
  con el renderer comprometido llegaría a `dotnet publish <lo que sea>`. `publish` está fuera de esa
  lista **a propósito**, con un comentario diciendo por qué y una prueba estructural que lo vigila.
- **Las tres banderas que dependen del RID se comprueban dos veces**: la interfaz atenúa la casilla
  con `supportsSingleFile` / `supportsReadyToRun` / `supportsTrimming`, y `publishArgs` las descarta
  otra vez. No es redundancia: lo que llega puede venir de `publish-profiles.json`, escrito por otra
  versión del IDE, y una bandera que se emite y no hace nada es peor que no ofrecerla.
- **`--self-contained` se emite siempre que haya RID, también en `false`.** Desde .NET 6 un `-r` sin
  la bandera avisa de que el valor por defecto cambió; dejarlo implícito es lo que hace que dos
  máquinas produzcan artefactos distintos con el mismo comando escrito.
- **Una casilla atenuada dice por qué**, y distingue "elige un destino" de "este modo no lo admite".
  Es la regla del ADR-023 y del ADR-033: atenuar y explicar, no esconder.
- **La carpeta del resultado se compone, no se rastrea.** El `-> ruta` de MSBuild está traducido al
  idioma del sistema (ADR-028), así que `publishOutputPath` reproduce la ruta con las mismas reglas
  que el SDK. Sin marco de destino devuelve `null` y no se ofrece abrir nada: enseñar una carpeta
  que no existe es peor que no enseñar ninguna.
- **La ruta de salida se sanea antes de ser un argumento**, y se comprueba contra el workspace si la
  hay. El saneado no es por inyección —todo viaja como array (ADR-004)— sino porque `-o out/` y
  `-o  out` producen una carpeta que luego no coincide con la que se enseña al terminar.
- **Las opciones se recuerdan por proyecto en `userData`, no en el repositorio.** Publicar en
  `D:\entregas\cliente` es una decisión de esta máquina; un `.pubxml` versionado diría lo contrario
  (ADR-015). Se anota **al lanzar**, no al terminar: si la publicación falla, lo que se quiere la
  próxima vez es el diálogo tal y como se dejó, para corregir una opción y reintentar.
- **Efecto lateral que valió la pena:** los tres bloques de `spawn` casi idénticos de
  `dotnet-service.ts` pasan a ser uno. El aviso de "no se ha podido ejecutar dotnet" sólo estaba en
  uno de los tres, así que un SDK ausente dejaba una instalación de paquete colgada sin decir nada.

---

### ADR-065 — La tira de pestañas se mueve y se colorea por proyecto, y el color no cambia solo
**Fecha:** 2026-08-27
**Contexto:** En una solución Clean Architecture de siete proyectos, tener abiertos cinco
`Program.cs` y cinco `appsettings.json` es lo normal, no un caso raro. En ese momento la tira de
pestañas deja de decir nada: el nombre del archivo es ambiguo y el que desambigua —el proyecto— no
está escrito en ninguna parte. Y con veinte pestañas abiertas la tira horizontal empieza a
desplazarse, que es cuando una tira vertical con nombres completos gana.
**Opciones:**
- (a) escribir el nombre del proyecto en cada pestaña;
- (b) un color por proyecto, derivado del nombre con una función hash;
- (c) un color por proyecto **asignado y guardado**, con el nombre como opción.

**Decisión:** (c), y la posición de la tira como ajuste de tres valores.
**Consecuencias:**

- **(a) sola no basta:** duplica el ancho de cada pestaña justo cuando el problema es que no caben,
  y en la tira horizontal el nombre se recorta antes que el del archivo. Se conserva como opción, y
  el tooltip lo dice siempre.
- **(b) reparte mal.** Un hash sobre el nombre da colisiones dentro de la misma solución —
  `Acme.Api` y `Acme.Application` pueden caer en el mismo tono— y ahí el código de colores deja de
  significar nada precisamente donde más falta hace.
- **El color no puede depender de la posición en la solución.** Si dependiera, crear un proyecto de
  pruebas recolorearía todos los demás y el código de colores que uno tenía memorizado cambiaría de
  golpe. Se asigna el hueco libre **más bajo** y se guarda por nombre; un proyecto que ya lo tenía
  conserva el suyo.
- **Ocho colores, no más.** Tienen que distinguirse de reojo en una franja de 2 px; con catorce
  tonos dejan de hacerlo, y dos proyectos compartiendo color siguen diciendo más que ninguno.
  Cada uno es un token de `theme.css` en los dos temas: el renderer aplica una clase, nunca un color
  calculado.
- **El proyecto de un archivo se decide por el prefijo de directorio más largo y por segmentos.**
  `src/Acme.Api` es prefijo **textual** de `src/Acme.ApiTests/Program.cs`, que es otro proyecto; y
  un proyecto dentro de la carpeta de otro (`src/Acme.Api/Extras`) se lleva sus archivos. Además se
  compara en minúsculas: en Windows la misma carpeta llega escrita de dos formas según venga del
  explorador o del `.sln`.
- **Un archivo que no está en ningún proyecto no lleva marca.** Un `README.md` de la raíz no
  pertenece a nada, e inventarle un color diría que sí.
- **La posición se resuelve entera en CSS**, con clases y áreas de rejilla. Mover el nodo de la tira
  en el DOM destruiría el contenedor de Monaco y obligaría a recrear el editor; y las clases se
  alternan sueltas en vez de reescribir `className`, porque sobre `.main` también vive
  `panel-collapsed`, que lo pone el panel inferior.
- **Con la tira a un lado, cada canto dice una cosa**: el exterior lleva el color del proyecto y el
  interior el acento de "pestaña activa". Puestos en el mismo borde, uno tapa al otro y la pestaña
  activa parece no tener proyecto.
- **La barra lateral se esconde; la de actividad, nunca.** Con las dos fuera, volver a enseñar la
  lateral exigiría recordar el atajo, y una interfaz de la que no se puede salir mirando no es una
  interfaz. Pulsar una herramienta con la lateral escondida la trae de vuelta.
- **`editor.layout()` a mano.** `automaticLayout` observa el **contenedor**, y lo que cambia aquí es
  la rejilla que lo envuelve: la notificación llega al fotograma siguiente y hasta entonces Monaco
  pinta con el ancho viejo, que se ve como una franja en blanco a la derecha del código. Medido:
  con la barra escondida, el área y el editor coinciden en 1184 px.
- **Los identificadores de comando siguen la convención del IDE (`view.toggle-sidebar`) y aceptan el
  de VS Code como alias.** Quien busca cómo ocultar la barra lateral escribe
  `workbench.action.toggleSidebar`; cambiar la convención entera por eso habría sido peor que
  aceptar los dos nombres.

---

### ADR-066 — El actualizador avisa antes de cerrar y, al volver, dice si se instaló
**Fecha:** 2026-08-27
**Contexto:** El actualizador in-app funcionaba y era mudo en los dos extremos del gesto más
intrusivo que hace el IDE. Al **entrar**: un botón que decía "Reiniciar y aplicar" cerraba la
ventana en el mismo clic, sin decir cuánto tardaba la instalación, quién la terminaba ni si la
aplicación volvía sola — y en macOS ni siquiera reiniciaba nada, sólo abría una imagen de disco. Al
**salir**: la sesión siguiente arrancaba idéntica se hubiera instalado o no. Cancelar el aviso de
permisos de Windows —un clic de más en un cuadro que aparece cuando ya nadie mira— dejaba al
usuario en la versión de siempre, con la tarjeta callada y sin ninguna forma de enterarse de que lo
que pidió no ocurrió.
**Opciones:**
- (a) dejarlo como estaba y explicar mejor el texto de la tarjeta;
- (b) leer el resultado del instalador y contarlo;
- (c) preguntar antes de cerrar, y **deducir** el resultado en el arranque siguiente comparando la
  versión que corre con la que se prometió.

**Decisión:** (c).
**Consecuencias:**

- **(b) no se puede.** El instalador se lanza `detached`, con `stdio: 'ignore'` y a un suspiro de
  que el proceso padre desaparezca: su código de salida no lo lee este IDE ni lo leerá nunca. Esa
  es la restricción del ADR-046, y es la buena — un padre que espera al instalador es un padre que
  bloquea el archivo que el instalador va a reemplazar.
- **La evidencia es la versión que corre.** Si es la prometida (o posterior), la instalación
  ocurrió. Si sigue siendo la de antes y el registro dice que el instalador se lanzó, no ocurrió.
  No hay tercer caso, y no hace falta preguntarle a nadie.
- **El intento se anota al lanzar, no al terminar.** Es el único momento en el que queda alguien
  para escribirlo. Por eso el campo se llama `attempts` y no `failures`: cuenta lo que se sabe.
- **Es el único `writeFileSync` del servicio, y está en `will-quit`.** La regla del ADR-051 —nada
  síncrono en el hilo principal— protege el repintado y el IPC de una ventana viva; ahí no queda
  ventana a la que hacer esperar un milisegundo, y un `await` no llegaría a resolverse.
- **El aviso vive en `state.outcome`, no en `state.status`.** La comprobación automática de los
  cinco segundos publica `up-to-date` nada más arrancar: metido en el estado, el "✅ ¡Actualizado!"
  se habría borrado solo antes de que a nadie le diera tiempo a leerlo. Sale con
  `acknowledgeOutcome`, que es una acción propia — cerrar una noticia no es posponer una
  actualización, y `dismiss` armaba `applyOnQuit` a ciegas.
- **Un plan que se completa a mano no puede declararse fallido.** En macOS, "se abrió el `.dmg` y
  todavía no se ha arrastrado nada" es el curso normal: acusar ahí al instalador pintaría un aviso
  en cada arranque hasta que alguien complete el arrastre, y al que decidió no completarlo, para
  siempre. Sólo el camino silencioso —que prometía terminar solo— puede incumplir.
- **Lo que falló no se reintenta solo.** Se conserva la descarga y se ofrece el botón, pero
  `applyOnQuit` queda desarmado: pudo cancelarse a propósito, y volver a lanzar en cada cierre lo
  que el usuario acaba de rechazar es insistir, no ayudar.
- **El aviso previo tiene un texto por plan, no uno genérico.** Un instalador silencioso y un `.dmg`
  prometen cosas distintas, y lo decide `planKind` —un dato del estado— en vez de una comparación
  sobre la frase de `plan`, que es texto de presentación. Y el botón dice lo que hace: "Cerrar e
  instalar" o "Abrir instalador". Ninguno de los dos promete un reinicio, porque el IDE no
  reinicia: se cierra y deja trabajando a otro.
- **`/S` pasa a llevar `--force-run`.** Un NSIS asistido (`oneClick: false`, que es lo que declara
  `electron-builder.yml`) instalado en silencio **no** relanza la aplicación por su cuenta: es la
  misma pareja de banderas que manda `electron-updater`. Sin ella, "y se vuelve a abrir al
  terminar" era una frase bonita en un cuadro de diálogo y un escritorio vacío en la realidad.
- **El registro pendiente lleva las notas de la versión.** Después de instalarla, el feed dice que
  no hay ninguna actualización: las novedades de la release que se acaba de aplicar no habría de
  dónde sacarlas. Y se leen con valores por defecto, porque el archivo lo escribe una versión del
  IDE y lo lee otra — un `pending.json` de la v2.7.0 no tiene `attempts` ni `notes`, y tratarlo
  como un intento fallido pintaría un aviso de error a todo el que actualice desde ahí.
- **La instalación pasa de `before-quit` a `will-quit`.** Ver la bitácora de errores: `before-quit`
  se emite al empezar a cerrar, y ese cierre todavía se puede cancelar.

---

### ADR-063 — Una cuarentena de Roslyn caduca al actualizar el IDE, y el motivo se dice entero
**Fecha:** 2026-08-27
**Contexto:** El IDE llevaba arrancando con `Roslyn LanguageServer 5.4.0-2.26177.7 (la fijada ya no
está en el feed…)`, o sea, con una versión **elegida sola** — exactamente lo que el ADR-040 existe
para evitar. El diagnóstico evidente era que Microsoft había retirado la fijada del feed.

Era falso. El feed publica hoy 763 compilaciones y `4.14.0-3.26423.7` **está entre ellas**. Lo que
pasaba es que estaba en cuarentena en este equipo desde el 25 de agosto, con el motivo "se cerró
solo con código 0" — la firma del ADR-043—, y `describeSelection` traducía ese estado con la frase
de otro: la de "ya no está en el feed". Un mensaje que manda a mirar al feed de Azure cuando el
problema está en un archivo de `userData`.

Y lanzado a mano, ese servidor **arranca perfectamente**: compone su gráfico MEF, aguanta, y con la
solución abierta contesta un `textDocument/hover` con C# de verdad. El veto no describía la
compilación: describía un bug del cliente que ya estaba arreglado.
**Opciones:**
- (a) subir la versión fijada a otra, que es lo que pedía el encargo;
- (b) borrar el archivo de cuarentena a mano y seguir;
- (c) que un veto caduque con la versión del IDE que lo dictó, y que el mensaje diga cuál de sus
  causas se ha dado.

**Decisión:** (c).
**Consecuencias:**

- **(a) habría sido cambiar una versión sana por otra** para tapar un veto obsoleto, y habría dejado
  el mecanismo intacto para volver a morder. La fijada no tenía nada malo: se comprobó lanzándola.
- **(b) arregla este equipo y ninguno más.** Cualquier usuario cuya instalación hubiera vetado la
  fijada por el bug del ADR-043 seguiría con una versión elegida sola para siempre, sin saberlo y
  sin forma de salir: la única salida existente (`pardonRoslynVersion`) sólo se dispara cuando la
  auditoría demuestra que la copia estaba corrupta.
- **Una cuarentena dice "esto no arrancó **con este cliente**".** De los fallos de arranque de
  Roslyn documentados en este proyecto, **dos han resultado ser bugs del cliente y no de la
  compilación**: contestar `null` a `workspace/configuration` (ADR-043) y mandar `shutdown` con
  `params: null` (este mismo ADR). Un veto dictado por una versión del IDE que ya no existe es un
  juicio sobre código que ya no se ejecuta, así que la entrada lleva `ideVersion` y sólo bloquea
  mientras esa versión sea la que corre. Si vuelve a fallar, se veta otra vez y ese juicio sí es
  sobre el código de ahora.
- **El veto caduca, no se borra.** Se conserva escrito porque es el único historial de qué falló y
  cuándo. Lo que cambia es si bloquea, no si existe.
- **Un estado degradado tiene que decir cuál de sus causas se ha dado**, no la más probable. La
  selección gana el motivo `quarantined`, que se distingue de `stable` en lo único que importa: si
  la versión sigue publicada. Con las dos a la vez —vetada y ausente— gana "no está", que es lo
  accionable: levantar un veto sobre algo que no se puede descargar no sirve de nada.
- **`shutdown` va sin parámetros.** Mandar `params: null` no es lo mismo que omitirlos: StreamJsonRpc
  cuenta los argumentos al deserializar y ante un `null` levanta `InvalidOperationException` fuera
  de todo `try`, matando el servidor con `0xE0434352`. Se arregla en el punto donde se componen los
  mensajes, no en la llamada, porque afecta a cualquier método sin parámetros.

### ADR-067 — El portapapeles de la terminal lo decide el IDE, no el intérprete
**Fecha:** 2026-09-08
**Contexto:** En las pestañas de pseudoterminal, `Ctrl+V` pegaba en PowerShell y pintaba `^V` en el
símbolo del sistema; `Ctrl+C` con texto seleccionado no copiaba en ninguna. xterm manda las dos
teclas al intérprete como U+0016 y U+0003 y llama a `preventDefault()`, con lo que tampoco llegan a
los `role` del menú. Que en PowerShell "funcionara" era PSReadLine leyendo el portapapeles del
sistema por su cuenta: la funcionalidad dependía de qué intérprete hubiera detrás.
**Opciones:**
- (a) dejar que los `role` del menú lo hagan, devolviendo `false` sin `preventDefault()` desde el
  manejador de xterm;
- (b) `navigator.clipboard` desde el renderer;
- (c) decidir el gesto en un módulo puro y ejecutarlo con un canal IPC de texto plano.

**Decisión:** (c).
**Consecuencias:**

- **(a) no cubre lo que la gente teclea.** `Shift+Insert`, `Ctrl+Insert` y `Ctrl+Shift+V` no son
  aceleradores de ningún `role`, y el botón secundario tampoco. Y hacer depender el pegado de que
  Electron reenvíe al menú un evento que el renderer no ha consumido es apoyarse en un detalle de
  plataforma que en macOS ya va por otro camino.
- **(b) no funciona aquí.** La ventana deniega todos los permisos del navegador
  (`setPermissionRequestHandler` → `false`), y leer el portapapeles es uno de ellos. Abrir ese
  permiso para una cosa lo abre para todo lo que corra en el renderer.
- **`Ctrl+C` son dos cosas y el contexto decide.** Con selección, copia; sin ella, U+0003 al
  intérprete. Es la convención de Windows Terminal y de VS Code, y la única que no deja o bien un
  `dotnet watch` que no se puede parar o bien una terminal que no sabe copiar.
- **En macOS no se toca nada.** `Cmd+C` / `Cmd+V` no los consume xterm, llegan a los `role` y
  xterm atiende los eventos `copy` y `paste` del DOM. `Ctrl+C` en un Mac es siempre interrumpir.
- **El `preventDefault()` es parte de la decisión.** Sin él, el evento sigue hasta el acelerador
  del menú y `role: 'paste'` pega otra vez a través del evento `paste` del DOM. Hay una prueba
  estructural que exige verlo junto al `return false`.
- **El canal es de texto plano y sólo lo usa la terminal.** El editor copia y pega a través de
  Monaco y de los `role` del menú; no hay motivo para que pase por aquí.

### ADR-068 — Limpiar una actualización no puede impedir que el IDE arranque
**Fecha:** 2026-09-08
**Contexto:** Al instalar una actualización en Windows, el instalador **relanza el IDE antes de
terminar de salir él**: durante ese solape hay dos procesos, y uno de ellos es el `.exe` que acaba
de arrancar al otro. El IDE recién abierto leía el registro pendiente, dictaminaba "instalada" y
borraba la carpeta de descargas — con el instalador dentro y en ejecución. Windows no deja borrar la
imagen de un proceso vivo, así que `rm` levantaba `EPERM`; `force: true` no cubre eso, sólo se traga
que la ruta no exista. Y la llamada estaba en el camino de arranque, antes del IPC, del menú y de la
ventana, dentro de un `then` sin `catch`.

El resultado era el peor fallo que ha tenido el IDE: un proceso **vivo, sin ventana** y sosteniendo
el bloqueo de instancia única. Sin ventana nunca se emite `window-all-closed`, así que nadie cerraba
nada; y con el bloqueo puesto, cada intento posterior de abrir el IDE —desde el menú de inicio, desde
el explorador, desde donde fuera— chocaba con él y salía en silencio. **El IDE no se podía volver a
abrir de ninguna manera y no había ningún error a la vista.** El único rastro en el disco era una
carpeta de descargas con el instalador dentro y sin `pending.json`: el borrado se llevó el archivo
pequeño y murió en el grande.

**Opciones:**
- (a) comprobar antes si el archivo se puede borrar;
- (b) no borrar nunca en el arranque y dejarlo siempre para más tarde;
- (c) que la limpieza sea de mejor esfuerzo y que **nada** del arranque pueda terminar sin ventana.

**Decisión:** (c), en tres capas.
**Consecuencias:**

- **(a) no sirve.** Entre la comprobación y el borrado el instalador sigue pudiendo estar vivo, y en
  Windows la forma de saber si un archivo está bloqueado es intentarlo. La pregunta correcta no es
  "¿puedo borrarlo?" sino "¿qué pasa si no puedo?".
- **Limpiar es tarea doméstica y ahora lo dice el código.** Se reintenta —`rm` reintenta ante
  `EPERM`, que es justo este caso— y, si no sale, se deja para el arranque siguiente. Ese arranque
  **recoge lo que quedó**: sin registro pendiente nadie volvía a mirar esa carpeta, así que un
  instalador huérfano de 130 MB se quedaba en el disco para siempre.
- **El actualizador arranca dentro de su propio `try`.** Es un servicio accesorio: que no pueda
  contar si la actualización se aplicó es una pena, que impida abrir una ventana es una avería.
- **La cadena de arranque tiene un `catch` que informa y cierra.** Enseñar una ventana a medias sería
  peor: un arranque interrumpido no ha registrado el IPC, así que su interfaz no respondería a nada.
  Cerrar devuelve al usuario a un estado del que puede salir volviendo a abrir el IDE, que es
  exactamente lo que antes no podía hacer.
- **Una segunda instancia sale con `app.exit(0)`, no con `app.quit()`.** `quit()` es una petición:
  anuncia la salida, emite `before-quit` y `will-quit`, y el módulo sigue ejecutándose entretanto —
  y en `main.ts` `will-quit` es donde se lanza el instalador de una actualización pendiente.
- **Y `second-instance` abre ventana si no hay ninguna**, con el arranque ya terminado. Es la red
  que convierte "el IDE no se abre y no sé por qué" en el gesto que el usuario acaba de hacer.
- **El instalador recibe además `--updated`**, que es lo que hace que NSIS **espere** a que el IDE
  termine de cerrarse en vez de matarlo mientras desmonta sus terminales y su servidor de lenguaje.
  Es el equivalente de `CloseApplications=yes` de un instalador de Inno Setup, que es como resuelve
  esto el proyecto DocGen.
- **Se verificó antes y después sobre la aplicación real**, con un `userData` aislado
  (`--user-data-dir`) y un instalador falso en marcha: el código publicado se queda sin ventana con
  `UnhandledPromiseRejectionWarning: EPERM` y hay que matarlo; el corregido escribe un aviso y llega
  a `SMOKE_OK`.

### ADR-069 — Cada release publica sus sumas SHA-256, y la firma queda cableada y vacía
**Fecha:** 2026-09-08
**Contexto:** Instalando el `Setup-x64.exe` de la v2.9.1 —descargado de la propia release, en un
equipo corporativo, y eligiendo "solo para mí"— Sophos Intercept X abortó la instalación con
*"Comportamiento malicioso 'lockdown' evitado en IDE de escritorio para C#"*. `lockdown` es
Application Lockdown, una regla de comportamiento, no una firma de malware; y la secuencia que ve
es: un `.exe` sin firmar bajado de internet escribe **otro** `.exe` sin firmar en
`%LOCALAPPDATA%\Programs` —sin pedir elevación, porque `perMachine: false`—, lo ejecuta al
instante (`runAfterFinish: true`) y ese proceso llama a la API de GitHub cinco segundos después.
Ninguno de los cuatro pasos es malicioso y los cuatro juntos son la definición de un *dropper*.

El diagnóstico no es lo que se decide aquí. Lo que se decide es qué falta en el repositorio para
poder **defender** el binario, y eran dos cosas: no había forma de comprobar que lo descargado es lo
que construyó la CI, y no había ningún sitio por donde entrase un certificado el día que lo hubiera.

**Decisión:**
- **La CI publica un `SHA256SUMS.txt` con cada release.** No sustituye a la firma Authenticode: la
  cubre mientras no la haya. Sin él, la respuesta a "esto lo he compilado yo" no se puede demostrar.
- **El formato es el de `sha256sum`**, con sus dos espacios, y no un JSON ni una tabla. Es lo que
  permite verificarlo sin instalar nada (`sha256sum -c`, o `Get-FileHash` a ojo desde PowerShell).
  Un formato propio obligaría a escribir el verificador, y el verificador que nadie ejecuta no
  verifica nada. Se comprobó contra el `sha256sum` del sistema, no sólo contra su propio lector.
- **Las sumas se calculan en el job que publica**, sobre los binarios ya traspasados entre jobs, y
  se **verifican con `--check`** antes de subir nada: rehashear el disco y comparar es el mismo
  gesto que hará quien se descargue la release. Un archivo de sumas que nadie ha ejecutado ni una
  vez es una promesa sin comprobar.
- **El archivo se adjunta fuera del array `assets`.** Dentro, un `dist/` sin un solo binario pero
  con su `SHA256SUMS.txt` pasaría por publicación correcta, porque la comprobación de "no llegó
  nada que adjuntar" dejaría de disparar. Es el mismo razonamiento del ensayo del ADR-060.
- **Las notas lo mencionan en una línea y sólo si el archivo existe.** Ni una tabla —el mismo cuerpo
  lo pinta la tarjeta del IDE, que no renderiza Markdown— ni un anuncio a ciegas: mandar a buscar un
  adjunto inexistente es peor con quien más se fía, que es justo quien va a ir a por él.
- **La firma se cablea vacía.** `signtoolOptions` declara SHA-256 y sellado RFC 3161, y **ningún
  certificado**: llega por `CSC_LINK` / `CSC_KEY_PASSWORD`, que es lo único compatible con un secret
  de GitHub. Con los secrets sin crear, electron-builder ve `cscLink === ""`, no busca más y
  empaqueta sin firmar — o sea, hoy no cambia absolutamente nada. El día que haya certificado, la
  única acción es crear dos secrets.
- **Y con certificado, un artefacto sin firmar para la publicación** (`verify-dist --require-signed`,
  condicionado a que el secret exista). Sin esa rama, un `.pfx` caducado o una contraseña mal
  copiada publicarían un binario sin firmar con toda la CI en verde: el patrón de siempre en este
  repositorio, una comprobación que sólo vigila el camino feliz. Sin certificado **no** se exige,
  porque una CI en rojo por diseño es la forma más rápida de que nadie vuelva a mirarla.

**Consecuencias:** el actualizador in-app ve ahora un artefacto más en cada release, y hay una
prueba en `updates.test.mjs` —que importa el nombre del archivo del script que lo escribe, no una
copia— exigiendo que `assetFor` no se lo lleve nunca en ninguna plataforma: bajarse las sumas en vez
del instalador dejaría una "actualización" de 200 bytes que no instala nada.

**Lo que esto no arregla:** el aviso de Sophos. Es un falso positivo de comportamiento y lo único
que lo elimina de raíz es firmar; mientras tanto hace falta una exclusión del administrador, y estas
sumas son lo que le permite comprobar de dónde sale el binario. Instalar "para todos los usuarios"
—en `Program Files`, con elevación— o usar el portable evita la secuencia que dispara la regla, pero
eso es una vuelta al problema, no una solución.

---

## Bitácora de iteraciones

### Iteración 1 — 2026-08-23 — Bootstrap
**Objetivo:** analizar el entorno y crear los documentos maestros.
**Hecho:**
- Sondeo del entorno (Node 24.19, .NET SDK 10.0.400, red OK).
- Creados `CLAUDE.md`, `AGENTS.md`, `PROJECT_DEVLOG.md`.
- Estructura de directorios creada; repositorio git inicializado.

**Errores encontrados:**
- *Síntoma:* el heredoc de bash falló con `unexpected EOF while looking for matching quote`
  al escribir un Markdown largo con comillas y backticks anidados.
  *Causa raíz:* el contenido con comillas simples desbalanceadas respecto al parser de la shell.
  *Arreglo:* usar la herramienta de escritura de archivos para documentos largos y reservar los
  heredocs para archivos cortos y sin comillas conflictivas.

**Siguiente:** cerrar la Fase 0 (`package.json`, `tsconfig.json`, `.gitignore`, agentes en
`.claude/agents/`, `npm install`) y arrancar la Fase 1.

### ADR-003 — Framework de pruebas de las plantillas: xUnit v2 + VSTest (no xUnit v3 + MTP)
**Fecha:** 2026-08-23
**Contexto:** Las soluciones generadas incluyen un proyecto de pruebas que debe ejecutarse con
`dotnet test` sin configuración adicional, tanto en SDK 9 como en SDK 10.
**Opciones:**
- (a) xUnit v3 + Microsoft.Testing.Platform: es la dirección futura del ecosistema.
- (b) xUnit v2 + VSTest (`Microsoft.NET.Test.Sdk` + `xunit.runner.visualstudio`).
**Decisión:** (b) xUnit 2.9.3 + xunit.runner.visualstudio 3.1.5 + Microsoft.NET.Test.Sdk 18.9.0.
**Consecuencias:** `dotnet test` funciona sin `global.json` ni `dotnet.config` en el SDK 10.
Cuando xUnit v3 y el orquestador MTP del SDK converjan, migrar es cambiar tres `PackageReference`
y quitar el `NoWarn` de xUnit1051. Se documenta en el README generado.

---

### Iteración 2 — 2026-08-23 — Motor de scaffolding y Clean Architecture
**Objetivo:** construir el motor de plantillas, el generador, la CLI y validar la primera
arquitectura compilando de verdad.

**Hecho:**
- Motor de plantillas estricto (`engine.ts`) con tokens, condicionales anidados y `{{else}}`.
  Un token o flag desconocido lanza error con número de línea: los typos rompen el test, no el
  `dotnet build`.
- Utilidades de nombres (`naming.ts`): validación de identificadores C#, pluralización inglesa,
  GUIDs deterministas por SHA-256 para que el `.sln` sea reproducible.
- Contexto de generación (`context.ts`) con matriz de versiones NuGet por framework.
- Emisor de `.sln` propio (`solution-file.ts`) con carpetas de solución, algo que `dotnet sln`
  no permite crear.
- Generador (`generator.ts`) y CLI `dotforge` completa.
- Blueprint **Clean Architecture** con 47 plantillas: Domain, Application, Infrastructure,
  WebApi (minimal API + OpenAPI + Scalar), Blazor interactivo y pruebas unitarias.
- Build con esbuild (`scripts/build.mjs`) y utilidad de devlog (`scripts/devlog.mjs`).

**Verificado con comandos reales:**
- `dotnet build` sobre la solución generada (net9.0): **0 errores, 0 advertencias**.
- `dotnet test` sobre la solución generada (net10.0): **14/14 pruebas correctas**.

**Errores encontrados y solucionados:**
1. *Síntoma:* `build/cli.js` fallaba con `SyntaxError: Invalid or unexpected token` en la línea 2.
   *Causa raíz:* el shebang estaba a la vez en el banner de esbuild y en el fuente TypeScript,
   así que quedaba uno en la línea 2, donde ya no es válido.
   *Arreglo:* el shebang lo pone sólo el banner de la build; se eliminó del fuente.
2. *Síntoma:* `error CS1061: WebApplication no contiene MapScalarApiReference`.
   *Causa raíz:* faltaba `using Scalar.AspNetCore;` en la plantilla de `Program.cs`.
   *Arreglo:* añadido. Cubierto por el test de build de la arquitectura.
3. *Síntoma:* `error CS0103: El nombre 'InteractiveServer' no existe en el contexto actual`
   al compilar `Products.razor`.
   *Causa raíz:* `@rendermode InteractiveServer` necesita
   `@using static Microsoft.AspNetCore.Components.Web.RenderMode` en `_Imports.razor`.
   *Arreglo:* añadido al `_Imports.razor` generado.
4. *Síntoma:* `dotnet test` fallaba con "Testing with VSTest target is no longer supported by
   Microsoft.Testing.Platform on .NET 10 SDK".
   *Causa raíz:* xUnit v3 arrastra Microsoft.Testing.Platform, y el SDK 10 exige un opt-in
   explícito. Ni `dotnet.config` ni `TestingPlatformDotnetTestSupport` lo resolvieron; con
   `global.json` sí arrancaba el runner pero descubría 0 pruebas, aunque el ejecutable de test
   lanzado a mano sí ejecutaba las 14.
   *Arreglo:* ADR-003, volver a xUnit v2 + VSTest. Verificado: 14/14 con `dotnet test`.
5. *Síntoma:* comandos de shell largos fallaban con `unexpected EOF while looking for matching
   quote` al escribir plantillas con heredocs.
   *Causa raíz:* el comando se trunca por encima de ~10 KB, dejando el heredoc sin cerrar.
   *Arreglo:* escribir las plantillas en lotes de menos de ~8 KB. Regla añadida a `CLAUDE.md`.

**Siguiente:** blueprints Hexagonal y DDD + CQRS, y la suite de tests automatizada que compila
las tres arquitecturas.

---

### Iteración 3 — 2026-08-23 — Hexagonal, DDD+CQRS y suite de pruebas
**Objetivo:** completar las tres arquitecturas y montar la suite automatizada que las verifica.

**Hecho:**
- Blueprint **Hexagonal**: Domain (núcleo puro), Ports (puertos de entrada/salida + servicios de
  aplicación) y Adapters (persistencia EF Core, notificaciones, Web API y Blazor).
- Blueprint **DDD + CQRS**: SharedKernel (Entity, AggregateRoot, ValueObject, IDomainEvent,
  Result), agregado con invariantes y eventos, despachador CQRS propio con envoltorios genéricos
  cacheados, pipeline de comportamientos (logging + validación), publicación de eventos de dominio
  al confirmar la unidad de trabajo.
- Suite de pruebas con el runner nativo de Node (`node --test`), sin dependencias añadidas:
  `tests/unit/` (motor, nombres, blueprints, .sln) y `tests/scaffold/` (build real + runtime).
- `scripts/run-tests.mjs` con grupos y `--filter`.

**Verificado con comandos reales:**
- `node --test tests/unit/*` → **106 pruebas, 0 fallos**.
- Matriz de scaffolding (6 combinaciones × 3 arquitecturas) → `dotnet build`
  **0 errores y 0 advertencias en las 6**.
- `dotnet test` sobre las 3 arquitecturas generadas en net10.0 → **todas correctas**.
- Prueba de humo en runtime: la Web API generada arranca y responde 201/409/400/404/204,
  filtra por búsqueda y publica su documento OpenAPI.

**Errores encontrados y solucionados:**
6. *Síntoma:* `toCamelCase('URLBuilder')` devolvía `urLBuilder`.
   *Causa raíz:* el cálculo `run.length - 1` sobraba: el lookahead del regex ya excluye del
   acrónimo la mayúscula que abre la siguiente palabra.
   *Arreglo:* minusculizar el run completo. Test de regresión en `tests/unit/naming.test.mjs`.
7. *Síntoma:* con `--db inmemory` fallaba el build con `CS1061: EntityTypeBuilder<T> no contiene
   ToTable / HasColumnName` en las tres arquitecturas.
   *Causa raíz:* `ToTable` y `HasColumnName` son API relacional; el paquete
   `Microsoft.EntityFrameworkCore.InMemory` no arrastra `Microsoft.EntityFrameworkCore.Relational`,
   que sí llega de forma transitiva con el proveedor SQLite.
   *Arreglo:* referenciar `Microsoft.EntityFrameworkCore.Relational` explícitamente en el proyecto
   de persistencia de las tres arquitecturas, para que el mapeo sea idéntico con ambos proveedores.
   Verificado además en runtime: la app con InMemory arranca y sirve el CRUD.
   *Cómo se detectó:* la matriz de la suite incluye combinaciones con `inmemory`. Sin esa
   combinación el fallo habría llegado al usuario final.
8. *Síntoma:* `_Imports.razor` del adaptador Blazor hexagonal emitía `warning CS0105` (using
   duplicado).
   *Causa raíz:* dos namespaces distintos de la plantilla Clean colapsaron al mismo namespace al
   adaptarla a Hexagonal.
   *Arreglo:* deduplicación del archivo. El test de build exige **0 advertencias**, no sólo 0 errores.
9. *Síntoma:* la prueba de humo fallaba con `Body is unusable: Body has already been read`.
   *Causa raíz:* leer el cuerpo de la respuesta con `.text()` en el mensaje de aserción y luego
   con `.json()`; el stream de `fetch` sólo se puede consumir una vez.
   *Arreglo:* leer una vez como texto y parsear a mano.

**Nota:** un 500 durante una prueba manual con `curl` resultó ser culpa del propio `curl`, que
enviaba el acento de "Periféricos" en Latin-1 en lugar de UTF-8, no del código generado.

**Siguiente:** el IDE en sí — shell de Electron, Monaco, cliente LSP, explorador de soluciones,
panel NuGet, wizard visual y empaquetado multiplataforma.

---

### ADR-004 — Terminal sin pseudoterminal, y lista blanca de programas
**Fecha:** 2026-08-23
**Contexto:** El IDE necesita una terminal integrada, pero un PTY real requiere `node-pty`, una
dependencia nativa.
**Opciones:**
- (a) `node-pty`: terminal completa, pero obliga a un paso de rebuild por plataforma y arquitectura,
  rompe la reproducibilidad del empaquetado y añade una dependencia binaria al instalador.
- (b) Ejecutor de comandos con `spawn` y `shell: false`: sin PTY, pero sin dependencias nativas.
**Decisión:** (b), con troceado propio de la línea en argv y lista blanca de programas
(`dotnet`, `git`, `npm`, …).
**Consecuencias:** cubre el flujo .NET real (compilar, `git status`, `npm ci`) y es inmune a la
inyección de comandos, porque los metacaracteres nunca llegan a un shell. No sirve para programas
interactivos; se dice explícitamente en la propia terminal y en el README.

### ADR-005 — F5 depura; ejecutar sin depurar es un comando aparte
**Fecha:** 2026-08-23
**Contexto:** F5 estaba mapeado a `dotnet run`. Al implementar NetCoreDbg había que decidir qué
hace F5.
**Decisión:** F5 inicia la depuración (como en Visual Studio y VS Code), `Ctrl+F5` inicia con Hot
Reload y "Ejecutar sin depurar" queda como comando de la paleta.
**Consecuencias:** el atajo hace lo que espera cualquiera que venga de Visual Studio. Depurar exige
haber compilado antes; si no, el error dice exactamente qué comando ejecutar.

---

### Iteración 4 — 2026-08-23 — El IDE: shell, LSP, herramientas .NET y depuración
**Objetivo:** construir el IDE completo alrededor del generador.

**Hecho:**
- Shell de Electron con la configuración de seguridad completa (aislamiento de contexto, sin
  integración de Node, CSP sin `eval` ni orígenes remotos, permisos denegados, navegación externa
  bloqueada) y apagado que no deja procesos huérfanos.
- Contrato IPC único y auditable en `src/shared/contracts.ts`; el preload no expone `ipcRenderer`.
- Cliente LSP con framing `Content-Length`, handshake completo y 10 proveedores de Monaco.
  Adquisición automática de `Microsoft.CodeAnalysis.LanguageServer` desde el feed `dotnet-tools`,
  con OmniSharp de respaldo.
- Decodificador ZIP propio en Node puro (directorio central, ZIP64, protección zip-slip) para no
  añadir dependencias al descargar el toolchain.
- Gramática Razor/Blazor, auto-cierre de etiquetas y 13 snippets.
- Explorador de soluciones (`.sln`, `.slnx`, `.csproj`, `Directory.Build.props`), panel NuGet,
  runner de tareas con diagnósticos clicables, terminal integrada y asistente visual.
- Depuración completa con NetCoreDbg: breakpoints en el margen, pila, variables, evaluación y pasos.
- Iconos multirresolución generados por código (codificador PNG, ICO e ICNS propios).
- Empaquetado con electron-builder y workflow de CI para los artefactos de macOS.

**Verificado con comandos reales:**
- `npm test` → **298 pruebas, 0 fallos** en los cuatro grupos.
- `npx electron . --smoke-test` → SMOKE_OK, incluida la tokenización real de Razor en el renderer.
- `npm run dist:win` → instalador NSIS de 117,2 MB y portable de 161,5 MB, verificados.
- La app **empaquetada** pasa el smoke test y sus plantillas generan una solución hexagonal que
  compila con 0 errores y 0 advertencias.
- Depuración real: breakpoint alcanzado, `i == 1`, `contador == 0`, continuar → `i == 2`.
- Descarga real del toolchain: Roslyn LanguageServer y NetCoreDbg extraídos con el ZIP propio.

**Errores encontrados y solucionados:**
10. *Síntoma:* toda la gramática Razor devolvía `text` — ninguna directiva se reconocía.
    *Causa raíz:* en Monarch, `@@` dentro de una expresión regular es el **escape de una sola
    arroba**. La regla `[/@@/, 'text']`, pensada para la arroba literal de Razor (`a@@b`), compilaba
    a `/^(?:@)/` y se comía el `@` de toda directiva antes de que se evaluara su regla.
    *Cómo se encontró:* volcando las reglas compiladas con el compilador Monarch invocado desde
    Node, tras comprobar que la gramática compilaba pero no casaba.
    *Arreglo:* `[/@@@@/, 'text']`. Cubierto por el smoke test, que tokeniza `correo@@ejemplo.com`.
11. *Síntoma:* `{ cases: ... }` dentro de la acción de un grupo compilaba pero no resolvía en
    ejecución.
    *Arreglo:* alternación generada desde un atributo **string** (`directivesPattern`). Monarch
    exige que una referencia `@atributo` dentro de un regex apunte a una cadena, no a un array;
    el compilador lo dice con un mensaje claro que sólo se ve invocándolo directamente.
12. *Síntoma:* al abrir una solución, la barra lateral mostraba el panel NuGet aunque el icono
    activo fuera el del explorador.
    *Causa raíz:* ambas vistas escribían en el mismo contenedor al recibir la solución y ganaba la
    última.
    *Arreglo:* cada vista tiene un flag `visible` y sólo pinta si está activa.
13. *Síntoma:* abrir un archivo por línea de comandos no lo abría en el editor.
    *Causa raíz:* el evento se emitía en `did-finish-load`, antes de que el renderer terminara de
    arrancar (Monaco tarda), así que no había nadie escuchando.
    *Arreglo:* sustituir el evento por una consulta (`workspace:pending-file`) que el renderer hace
    cuando ya está listo. Además, la raíz del workspace pasa a ser la carpeta de la solución más
    cercana, no la del archivo.
14. *Síntoma:* el explorador mostraba todos los proyectos sin target framework.
    *Causa raíz:* las soluciones generadas declaran `TargetFramework` en `Directory.Build.props`,
    no en cada `.csproj`.
    *Arreglo:* `readInheritedProperties` sube buscando el `Directory.Build.props` más cercano.
    Lo detectó una prueba unitaria que parsea una solución generada por el propio scaffolder.
15. *Síntoma:* la adquisición del servidor de lenguaje bajaba una versión antigua (4.8.0 en vez de
    5.4.0).
    *Causa raíz:* el feed devuelve las versiones en orden descendente y el código cogía la última.
    *Arreglo:* `pickLatestVersion`, que compara segmentos numéricos. Con casos de prueba.
16. *Síntoma:* un acelerador de menú con un carácter no ASCII se aceptaba en la configuración pero
    Electron lo rechazaba en ejecución, dejando el atajo muerto.
    *Arreglo:* `Ctrl+J` para la terminal, y una aserción en el smoke test que falla si Electron
    vuelve a quejarse de un acelerador.

**Estado final:** 60/63 tareas del roadmap. La única pendiente real es F5.7 (artefactos de macOS),
bloqueada por plataforma y resuelta mediante el workflow de CI incluido.

---

### ADR-006 — Sistema de iconos propio en vez de una librería
**Fecha:** 2026-08-23
**Contexto:** La interfaz usaba glifos de texto (`⬡`, `🗀`, `C#`, `@`) como iconos. Se renderizan
distinto en cada sistema, no heredan el color, no se alinean con el texto y algunos son emoji a
todo color que rompen la coherencia visual.
**Opciones:**
- (a) Lucide / Phosphor como dependencia: cientos de iconos, licencia permisiva, cero trabajo.
- (b) Un set propio dibujado sobre la misma rejilla y con el mismo lenguaje visual.
**Decisión:** (b), 61 iconos en `src/renderer/icons.ts`, rejilla 24×24, trazo 1.75, extremos
redondeados, todo heredando `currentColor`.
**Consecuencias:** cero dependencias nuevas y control total sobre las piezas que no existen en
ningún set genérico (la almohadilla de C#, la arroba de Razor, la caja de proyecto .csproj). A
cambio, hay que dibujarlos y revisarlos: por eso existe el modo `--icons`, que los pinta todos a
varios tamaños, y las pruebas que validan la geometría de cada ruta.

### ADR-007 — Barra de estado neutra en vez de una banda de acento
**Fecha:** 2026-08-23
**Contexto:** La barra de estado era una banda violeta saturada a todo lo ancho de la ventana.
**Decisión:** superficie neutra (`--bg-deep`) con el color reservado para lo que reclama atención:
errores en rojo, tarea en curso en ámbar, servidor de lenguaje listo en verde.
**Consecuencias:** el acento vuelve a significar algo. Cuando todo va bien, la barra desaparece
del campo de visión, que es exactamente lo que debe hacer.

### ADR-008 — Anidamiento de archivos que agrupa, nunca oculta
**Fecha:** 2026-08-23
**Contexto:** Una solución Blazor genera tres archivos por componente (`Home.razor`,
`Home.razor.cs`, `Home.razor.css`) y varios `appsettings.<Entorno>.json`. El árbol se llena de
filas que nadie busca.
**Decisión:** los archivos satélite se agrupan bajo su archivo principal, con una regla explícita
por patrón (`nestingParentsOf`).
**Consecuencias:** el árbol de un proyecto Blazor pierde alrededor de un tercio de sus filas. La
regla dura es que **si el padre no existe, el hijo se queda como raíz**: agrupar nunca puede
hacer que un archivo desaparezca. Hay un test dedicado a esa invariante y otro que comprueba que
la suma de nodos raíz e hijos es siempre igual al número de archivos de entrada.

---

### Iteración 5 — 2026-08-23 — Rediseño integral de UI/UX
**Objetivo:** hacer la interfaz sencilla, limpia y amable a la vista, con un árbol de soluciones
.NET realmente comprensible.

**Hecho:**
- **Iconografía.** 61 iconos vectoriales propios sustituyen a los glifos de texto. Incluyen marcas
  específicas del ecosistema (C#, Razor, solución, proyecto) y de carpetas con significado
  (Controllers, Models, Services, Pages, Components, wwwroot, Domain, Ports, Commands, Events…).
- **Color y tipografía.** Paleta suave: el fondo más oscuro es `#1b1d27` y el texto más claro
  `#c8cee2`; el violeta de .NET se lleva a un pastel `#a58cf5` y el `#512BD4` original queda sólo
  para el logotipo. Escala tipográfica y de espaciado en tokens. Sintaxis resintonizada dentro de
  un rango de saturación estrecho para que ningún color salte por encima del resto.
- **Explorador.** Jerarquía real de la solución, insignias de tipo de proyecto, guías de sangría
  con resalte del nivel activo, anidamiento de archivos satélite, filtro por nombre, "contraer
  todo", menú contextual con iconos, y el proyecto de aplicación abierto por defecto para que
  abrir una solución no cueste tres clics antes de ver código.
- **Declutter.** Barra de actividad reducida a cinco herramientas más ajustes; barra de estado con
  sólo SDK, LSP, rama de Git y problemas; el `.csproj` ya no se repite dentro de su propio
  proyecto; el target framework sólo se muestra cuando la solución mezcla varios.
- **Ajustes** como vista de la barra lateral, con efecto inmediato.
- **Asistente de arquitecturas** con tarjetas, icono por arquitectura y diagrama de capas con
  flechas, que comunica la forma de cada arquitectura mejor que cualquier párrafo.

**Verificado con comandos reales:**
- `npm test` → **359 pruebas, 0 fallos** (61 nuevas para las reglas visuales).
- `npx electron . --icons` → las 61 piezas revisadas a 16 y 24 px.
- Tema oscuro: chrome en `rgb(23, 25, 34)`. Tema claro: `rgb(232, 234, 240)`. Medido dos veces:
  con `--probe=` sobre `getComputedStyle` y leyendo los bytes del PNG capturado.

**Errores encontrados y solucionados:**
17. *Síntoma:* los nombres de proyecto salían truncados (`Acme.Shop.Sh…`).
    *Causa raíz:* la insignia y el target framework competían por el ancho con el nombre, que es
    justo lo que el usuario está leyendo.
    *Arreglo:* insignias cortas (`Lib`, `CLI`, `Job`) y el framework sólo cuando la solución
    mezcla varios; el dato completo vive en el tooltip.
18. *Síntoma:* el explorador y el panel NuGet se pintaban los dos sobre el mismo contenedor al
    cargar una solución, y ganaba el último: la barra mostraba NuGet con el icono del explorador
    activo.
    *Arreglo:* cada vista de la barra lateral tiene un flag `visible` y sólo pinta si está activa.
19. *Síntoma:* al abrir un workspace, la salida registraba dos veces "N proyectos".
    *Causa raíz:* la solución llegaba por dos caminos, la llamada directa y el evento difundido
    por el proceso principal.
    *Arreglo:* `applySolution` detecta la segunda vuelta sobre la misma solución y no repite el
    aviso ni recarga el árbol.
20. *Síntoma:* el indicador del SDK no aparecía en la barra de estado.
    *Causa raíz:* un heredoc de shell se comió los backslashes de una expresión regular y
    `/^(\d+\.\d+)/` quedó como `/^(d+.d+)/`.
    *Arreglo:* corregida con edición directa del archivo. Es la tercera vez que un heredoc largo
    corrompe escapes; la regla ya está en `CLAUDE.md`.
21. *Síntoma:* el diagrama de capas del asistente dejaba una flecha suelta al final de línea
    cuando las capas se envolvían.
    *Arreglo:* cada capa viaja en el mismo grupo que su flecha.
22. *Síntoma:* dos iconos dibujados a mano (`hammer` y `tool`) eran ilegibles a 16 px.
    *Cómo se encontró:* la galería `--icons`, que es justamente para esto.
    *Arreglo:* rediseñados; el martillo pasó a cabeza inclinada y mango, y la llave inglesa a una
    silueta cerrada.

**Nota sobre el método:** varias capturas del tema claro parecían mostrar el chrome oscuro sobre
contenido claro, lo que apuntaba a un fallo del tema. Dos medidas independientes dicen lo
contrario: `--probe=` devuelve `rgb(232, 234, 240)` para la barra de título y la de estado, y
`scripts/read-pixels.mjs`, que decodifica el PNG y lee los bytes, devuelve exactamente el mismo
valor en esas coordenadas. El archivo es correcto; lo que engañaba era el visor. De ahí salieron
`--probe=`, `--ui=` y el lector de píxeles: un color se mide, no se mira.

**Cierre de la iteración — hallazgos de la compilación de prueba:**
23. *Síntoma:* la lista de recientes mostraba dos entradas idénticas, `Acme.Shop` con la ruta
    `C:\Users\Sergio\AppData\Local\Te…` repetida.
    *Causa raíz:* no era un duplicado. Eran dos soluciones distintas con el mismo nombre en
    carpetas distintas, y el recorte por el final borraba justo la parte que las distingue.
    *Arreglo:* la entrada muestra ahora las dos carpetas contenedoras (`…\scratchpad\final` frente
    a `…\Temp\dfdemo`) y la ruta completa vive en el tooltip. La función vive en
    `src/renderer/paths.ts`, fuera del DOM, y tiene sus propias pruebas.
24. *Síntoma:* el muestreo de píxeles de `--screenshot=` informaba de un color de barra de estado
    que no correspondía a ningún token.
    *Causa raíz:* las coordenadas de muestreo estaban fijas en el código y caían fuera del lienzo
    capturado; el recorte devolvía un píxel que no era de nadie.
    *Arreglo:* las coordenadas se derivan del tamaño real de la imagen. Confirmado contra
    `getComputedStyle`: las cuatro zonas coinciden ahora con sus tokens.

**Compilación de prueba final:** `npm run icons`, `npm run dist:win`, `verify-dist.mjs --require win`
y arranque real del ejecutable empaquetado (`SMOKE_OK`). Capturas regeneradas desde el binario y
desde el código con el mismo resultado.

### ADR-009 — La versión se declara una sola vez, en `package.json`
**Fecha:** 2026-08-23
**Contexto:** El número `1.0.0` estaba escrito a mano en cuatro sitios: el CLI, el `clientInfo` que
el cliente LSP envía en el handshake, el manifiesto `dotforge.json` de cada solución generada y el
propio `package.json`. Al subir a 1.1.0 se vio el problema: basta olvidar uno para que el IDE diga
una versión, el instalador otra y el manifiesto una tercera.
**Decisión:** `package.json` es la única fuente. `scripts/build.mjs` inyecta el valor como constante
de compilación (`define` de esbuild) y `src/shared/version.ts` lo expone como `APP_VERSION`, con un
`0.0.0-dev` de reserva por si alguien ejecuta el código sin pasar por el build.
**Consecuencias:** `npm version` ya basta para cambiarla en todas partes. El coste es que la versión
sólo es correcta en el código compilado, no leyendo el fuente, que es un intercambio razonable
porque el producto siempre se ejecuta compilado.

---

### Iteración 6 — 2026-08-23 — v1.1.0
El rediseño de UI/UX añade funcionalidad —vista de ajustes, anidamiento de archivos, sistema de
iconos, estado de Git en la barra inferior, modos de diagnóstico `--icons`, `--ui=` y `--probe=`—,
así que por semver le corresponde subir el segundo número, no el tercero: 1.0.0 → **1.1.0**.

**Hecho:**
- Versión centralizada (ADR-009) y `1.1.0` en `package.json`.
- Artefactos regenerados: los nombres los compone electron-builder con `${version}`, así que pasan
  a `DotForge IDE-1.1.0-*` sin tocar `electron-builder.yml`.
- Referencias actualizadas en `README.md` y en la cabecera de esta bitácora.

**Verificado:** `node build/cli.js --version` → `1.1.0`; los tres bundles (`cli`, `scaffold`, `main`)
contienen el literal inyectado; `npm test` en verde; `verify-dist` reconoce los artefactos nuevos.

### ADR-010 — El README didáctico es una plantilla por arquitectura, no texto generado en código
**Fecha:** 2026-08-23
**Contexto:** Cada solución generada debe llevar un `README.md` extenso que enseñe la arquitectura
elegida. Había tres formas de producirlo.
**Opciones:**
- (a) Componerlo en TypeScript a partir de `BlueprintInfo` (capas, patrones, highlights): una sola
  implementación, pero el texto queda troceado en literales dentro del código y las tres
  arquitecturas acaban compartiendo una prosa genérica que no enseña nada concreto.
- (b) Un `README.md.tmpl` común en `_common/` con condicionales por `isClean` / `isHexagonal` /
  `isDdd`: un único archivo de 2.000 líneas donde el 80% del contenido está dentro de un
  condicional. Ilegible y muy fácil de romper.
- (c) Un `README.md.tmpl` por arquitectura, junto a las plantillas de código que documenta.
**Decisión:** (c). El README vive en `src/scaffold/templates/<arquitectura>/README.md.tmpl`.
**Consecuencias:** el documento puede hablar de archivos, clases y namespaces reales de esa
arquitectura —`IManage{{EntityPlural}}` en hexagonal, `IDispatcher` en DDD, `I{{Entity}}Service` en
clean—, que es justo lo que lo hace didáctico. A cambio hay contenido repetido entre los tres
(sección de comandos, gestión de paquetes), que se acepta: son tres documentos independientes y
cada uno debe poder leerse solo. La coherencia entre ellos la vigilan las pruebas de
`tests/unit/blueprints.test.mjs`, que exigen las mismas seis secciones en los tres.

### ADR-011 — Los diagramas se escriben en Mermaid, no en ASCII ni como imagen
**Fecha:** 2026-08-23
**Contexto:** El README necesita un diagrama de dependencias entre capas y otro del recorrido de
una petición.
**Opciones:** (a) ASCII art, (b) una imagen SVG/PNG generada, (c) Mermaid embebido en el Markdown.
**Decisión:** (c) Mermaid. Lo renderizan GitHub, GitLab, Azure DevOps y los previsualizadores de
Markdown más habituales; sigue siendo legible como texto plano si no hay renderizador; y viaja
dentro del propio archivo, sin binarios que versionar.
**Consecuencias:** hay una trampa que documentar (ver la bitácora de la iteración 7): la forma
hexagonal de Mermaid se escribe con dobles llaves, que es exactamente la sintaxis de token del
motor de plantillas. Las plantillas no pueden usar esa forma de nodo, y hay una prueba que lo
comprueba.

---

### Iteración 7 — 2026-08-23 — README didáctico por arquitectura
**Objetivo:** que toda solución generada por el wizard lleve en su raíz un `README.md` que enseñe
la arquitectura elegida: qué es, qué código va en cada capa, qué código tiene prohibido estar ahí,
cómo añadir una funcionalidad paso a paso, qué trae el ejemplo incluido y con qué comandos se
compila, se prueba y se ejecuta.

**Hecho:**
- Tres plantillas nuevas: `templates/clean/README.md.tmpl` (780 líneas),
  `templates/hexagonal/README.md.tmpl` (734) y `templates/ddd/README.md.tmpl` (863). Se emiten como
  cualquier otra plantilla, así que el filtro `includeFile` y el motor de condicionales funcionan
  sin tocar el generador.
- Seis secciones fijas en las tres: introducción y diagramas, estructura y responsabilidades, guía
  paso a paso, ejemplo incluido, comandos, y antipatrones.
- Dos diagramas Mermaid por arquitectura: uno de dependencias entre proyectos (con los proyectos de
  presentación condicionados a lo que el usuario haya pedido) y una secuencia del recorrido de una
  petición de alta, desde el cliente hasta la base de datos.
- Tabla "✅ DEBE estar aquí / ❌ TIENE PROHIBIDO estar aquí" por cada proyecto, más la matriz
  completa de la regla de dependencia y las dependencias permitidas de cada uno.
- Guía paso a paso con un caso de uso real y distinto en cada arquitectura, con el código C# que
  hay que escribir en cada paso: descatalogar la entidad de ejemplo (clean y DDD, este último con evento de
  dominio) y reservar unidades (hexagonal, con puerto de salida nuevo). Termina en una checklist.
- Todo el contenido está condicionado a las opciones del wizard: presentación (`hasWebApi`,
  `hasBlazor`, `hasBoth`), pruebas (`hasTests`), base de datos (`useSqlite`, `useInMemory`) y
  framework. Una solución sólo API no documenta Blazor, y una sin pruebas no habla de `dotnet test`.
- Los puertos reales de la solución (`ApiHttpsPort`, `BlazorHttpsPort`) aparecen en las URLs, así
  que las direcciones del README son las que de verdad abre `dotnet run`.
- El resultado del wizard (`src/renderer/views/wizard.ts`) y la salida de la CLI
  (`src/cli/index.ts`) avisan de que el README existe y qué contiene.
- Pruebas nuevas: 15 en `tests/unit/blueprints.test.mjs` (secciones obligatorias, diagramas,
  reglas de dependencia, pasos de la guía, comandos) y una por cada caso de la matriz en
  `tests/scaffold/scaffold-build.test.mjs`, que valida el README **generado**: dos diagramas
  Mermaid, secciones, coherencia con las opciones y que no documente un proyecto que no existe.

**Errores encontrados:**
- *Síntoma:* el árbol de carpetas del README salía descuadrado: los comentarios estaban alineados
  en columna y, al sustituir `{{Solution}}` por `Ac.Shop` y `{{Entity}}` por `Product`, cada línea
  cambiaba de ancho.
  *Causa raíz:* alinear con espacios asume un ancho que sólo se conoce en tiempo de render.
  *Arreglo:* el comentario se separa con ` — ` en vez de con una columna de espacios. Nunca se
  descuadra, sea cual sea el nombre de la solución.
- *Síntoma:* líneas en blanco sueltas dentro del árbol, justo antes de cada proyecto opcional.
  *Causa raíz:* una línea que sólo contiene `{{#if}}` deja su salto de línea al desaparecer, y las
  líneas de relleno `│   │` del árbol se sumaban a ese hueco.
  *Arreglo:* las líneas de relleno se dejan vacías y `normalizeOutput` colapsa los saltos
  sobrantes; el hueco pasa a ser un separador visual coherente entre proyectos.
- *Síntoma:* la herramienta de escritura guardó las tres plantillas en CRLF, contra la convención
  del repositorio (LF). *Arreglo:* normalizadas con `tr -d '\r'` y verificadas leyendo los bytes,
  no confiando en `grep`. Es la trampa ya documentada en `CLAUDE.md`; ha vuelto a aparecer.
- *Síntoma:* con `--ui blazor`, el encabezado del README anunciaba la ruta `/api/products` y el
  diagrama de secuencia empezaba con un `POST` HTTP, en una solución sin Web API.
  *Causa raíz:* dos frases sueltas fuera de los condicionales de presentación.
  *Arreglo:* condicionadas; ahora esa variante habla de la página `/products`. La prueba de la
  matriz comprueba que el README no mencione ningún proyecto que no se haya generado.
- *Trampa nueva (anotada en `CLAUDE.md`):* en Mermaid, `A{{Texto}}` es un nodo hexagonal, y el
  motor de plantillas lo interpretaría como un token. Las plantillas no pueden usar esa forma de
  nodo; hay una prueba que lo verifica.

**Verificado:** `npm run build` (157 plantillas), `npm test` en verde de punta a punta, y
generación real de las tres arquitecturas más las variantes `--ui webapi --no-tests --db inmemory`
y `--ui blazor`, revisando el Markdown resultante.

### Iteración 8 — 2026-08-23 — v1.2.0
El README didáctico es funcionalidad nueva de las soluciones generadas y no rompe nada de lo
anterior, así que por semver le corresponde el segundo número: 1.1.0 → **1.2.0**.

**Hecho:**
- `1.2.0` en `package.json`, que por ADR-009 es la única fuente: los bundles reciben el valor por
  `define` de esbuild y el manifiesto `dotforge.json` de cada solución lo hereda.
- Nombres de artefacto actualizados en `README.md` (electron-builder los compone con `${version}`,
  así que `electron-builder.yml` no se toca).

**Verificado:** `node build/cli.js --version` → `1.2.0`; el literal inyectado aparece en los
bundles `cli`, `scaffold` y `main`; `npm test` en verde.

### Iteración 9 — 2026-08-23 — `dist/` se poda sola entre versiones
**Síntoma:** tras `npm run dist:win` con la 1.2.0, `/dist` contenía los artefactos de la 1.1.0 y
los de la 1.2.0 a la vez: 279 MB de instaladores viejos y dos `.exe` parecidos donde es fácil
subir el que no era.

**Causa raíz:** `artifactName` incluye `${version}`, así que cada release escribe archivos con
nombre nuevo, y electron-builder no limpia su directorio de salida: sólo reescribe lo que vuelve
a generar con el mismo nombre (`win-unpacked`, `builder-*.yml`).

**Opciones consideradas:**
- (a) Borrar `/dist` entera antes de empaquetar. Se descarta: `dist:win` y `dist:mac` se ejecutan
  por separado —y en máquinas distintas—, así que el segundo se llevaría por delante lo del
  primero. Y `dist:all` tendría el mismo problema entre sus dos mitades.
- (b) Quitar `${version}` del nombre de artefacto. Se descarta: se pierde la trazabilidad de qué
  instalador es cuál, que es justo lo que evita subir el equivocado.
- (c) Podar sólo lo que lleve un sello de versión distinto del actual. **Elegida.**

**Hecho:**
- `scripts/lib/dist-artifacts.mjs`: la regla, como función pura y probable sin tocar disco.
- `scripts/prune-dist.mjs`: recorre `dist/`, informa de tamaño y borra. Acepta `--dry-run`.
- `pack`, `dist:win`, `dist:mac` y `dist:all` lo ejecutan **antes** de empaquetar; hay una prueba
  que verifica ese orden, porque al revés borraría lo que se acaba de construir.
- Expuesto también como `npm run prune:dist`, documentado en `CLAUDE.md` y en `README.md`.
- 7 pruebas nuevas en `tests/package/packaging.test.mjs`.

**Decisión que conviene recordar:** la regla es deliberadamente conservadora. Un archivo cuyo
nombre contiene el sello de la versión actual **nunca** se borra, aunque sea una preliberación
(`1.2.0-beta.1` estando en la `1.2.0` sobrevive). Distinguir ese caso exigiría mantener una lista
de sufijos de destino (`win`, `mac`, `arm64`, `Setup`, …) y acertar siempre: equivocarse borraría
el instalador recién compilado. Dejar basura es recuperable; borrar el artefacto bueno, no.

**Verificado:** `node scripts/prune-dist.mjs --dry-run` sobre el `dist/` real listó exactamente los
tres archivos de la 1.1.0; la ejecución liberó 278.8 MB y dejó intactos los de la 1.2.0,
`win-unpacked` y los `builder-*.yml`. `npm run test:package` en verde (57 pruebas).

### Iteración 10 — 2026-08-23 — Depurar aplicaba Production: el perfil de arranque se ignoraba
**Síntoma:** al depurar (F5) una solución hexagonal con UI Blazor, el log decía
`Hosting environment: Production`, `Now listening on: http://localhost:5000`, `The WebRootPath was
not found: ...\bin\Debug\net10.0\wwwroot` y repetía en cada petición `Static Web Assets are not
enabled`. Con `Ejecutar` (que es `dotnet run --project`) no pasaba.

**Causa raíz:** dos problemas distintos que se manifestaban juntos.
1. `dotnet run` aplica el perfil de `Properties/launchSettings.json`; el depurador no. El
   controlador lanzaba el `.dll` con `cwd = bin/Debug/<tfm>` y **sin ninguna variable de entorno**,
   así que ASP.NET asumía Production: puerto 5000 en vez de los del perfil, y sin los static web
   assets, que sólo se activan solos en Development. `DebugSession` ya aceptaba `env` en la
   petición `launch` de DAP; simplemente nadie lo rellenaba.
2. La plantilla Blazor no traía favicon, así que cada carga de página dejaba un `404 /favicon.ico`
   en el log. Eso no dependía del entorno.

**Hecho:**
- `src/main/services/launch-settings.ts`: lee el perfil, elige cuál aplicar con el mismo criterio
  que Visual Studio (sólo `commandName: "Project"`; el homónimo del proyecto y si no el primero) y
  traduce `applicationUrl` a `ASPNETCORE_URLS`, que es lo que hace `dotnet run`. No lanza nunca: un
  `launchSettings.json` ausente es lo normal en una biblioteca, y uno corrupto no puede impedir
  depurar, así que se devuelve un aviso que la sesión escribe en su salida.
- `DebugTarget` lleva ahora `env`, `launchProfile` y `launchWarning`; el controlador los pasa al
  `launch` de DAP y anuncia en la consola qué perfil ha aplicado.
- Exportado por `src/main/testable.ts` para poder probarlo con Node puro.
- Plantillas Blazor (las tres arquitecturas): `favicon.svg` propio de cada arquitectura —capas
  concéntricas, hexágono, frontera de agregado— enlazado desde `App.razor`, y
  `builder.WebHost.UseStaticWebAssets()` en `Program.cs`, para que la aplicación encuentre
  `wwwroot` también cuando la lanza un depurador desde `bin/`. En una app publicada no hace nada.
- 17 pruebas nuevas en `tests/unit/launch-settings.test.mjs`, con la fixture generada por el propio
  scaffolder: así también se verifica que el `launchSettings.json` que produce es utilizable.

**Verificado sobre una solución real** (`Hx`, hexagonal + Blazor, net10.0), lanzando el binario de
`bin/Debug` igual que hace el depurador:
- Sin perfil, ya sólo con `UseStaticWebAssets()`: desaparecen los avisos de `WebRootPath` y de
  `Static Web Assets` (0 apariciones en el log), y `/favicon.svg` responde 200.
- Con el entorno del perfil (`ASPNETCORE_ENVIRONMENT=Development` + `ASPNETCORE_URLS`):
  `Hosting environment: Development`, escucha en 5355/5354 en vez de en el 5000, y desaparece
  también `Failed to determine the https port for redirect`. `/`, `/products` y `/favicon.svg`
  responden 200.
- Queda un único aviso, ajeno al IDE: el certificado de desarrollo no está confiado en la máquina.
  Se resuelve con `dotnet dev-certs https --trust`.

**Nota de método:** el `404 /favicon.ico` que aparece al pedirlo con `curl` es esperado y no se
corrige: un navegador con `<link rel="icon">` en el documento no pide `/favicon.ico`.


### ADR-012 — Una sola sesión de depuración, aunque el perfil arranque varios proyectos
**Fecha:** 2026-08-23
**Contexto:** El selector de inicio permite arrancar varios proyectos a la vez (API + UI). La
pregunta inmediata es qué significa "depurar" un perfil de tres proyectos.
**Opciones:**
- (a) Una sesión de NetCoreDbg por proyecto. Es lo que hacen Visual Studio y Rider. Obliga a un
  gestor de sesiones, a enrutar cada breakpoint a la sesión que corresponde, a decidir qué pila y
  qué variables se enseñan cuando hay dos procesos detenidos y a una UI para cambiar de sesión.
- (b) Depurar el primer proyecto del perfil y arrancar el resto sin depurador.
- (c) No permitir depuración en perfiles multiproyecto.
**Decisión:** (b). El primer proyecto del perfil se engancha al depurador; los demás arrancan con
`dotnet run`. El modal lo dice explícitamente antes de guardar el perfil, con el nombre del
proyecto que se va a depurar.
**Consecuencias:** el caso real más común —depurar la API mientras la UI corre al lado— queda
cubierto con una arquitectura que ya existe (`DebugController` tiene una `DebugSession`). A cambio,
poner un breakpoint en el segundo proyecto no detiene nada, y por eso se avisa en la interfaz en
vez de dejar que el usuario lo descubra. (a) queda como trabajo futuro: implica un
`DebugSessionManager` y un selector de sesión activa, que es una fase entera.

### ADR-013 — "Sin depurar" usa Hot Reload en las webs y `dotnet run` en el resto
**Fecha:** 2026-08-23
**Contexto:** El conmutador de la barra superior tiene dos posiciones, no tres, pero por debajo hay
tres formas de arrancar: con depurador, con `dotnet run` y con `dotnet watch`.
**Decisión:** el modo "Sin depurar" arranca los proyectos web con `dotnet watch` (Hot Reload) y los
ejecutables de consola con `dotnet run`.
**Consecuencias:** el conmutador sigue teniendo dos posiciones, que es lo que un usuario espera, y
aun así se obtiene recarga en caliente donde de verdad sirve. Recargar en caliente una aplicación
de consola reinicia el proceso a cada cambio y ensucia la salida sin aportar nada. La regla vive en
`launchPlan`, que es una función pura y está probada caso a caso.

### ADR-014 — Sugerencias por prefijo, sin fuzzy matching
**Fecha:** 2026-08-23
**Contexto:** El autocompletado de la terminal podía imitar al del editor (coincidencia difusa,
puntuación por relevancia) o comportarse como una shell.
**Decisión:** coincidencia por prefijo, con las listas ordenadas por frecuencia real de uso y sin
reordenar por puntuación.
**Consecuencias:** escribir `git st` y pulsar Tab da `git status` siempre, hoy y dentro de un mes.
Ese determinismo es lo que permite escribir sin mirar. El coste es que `gst` no encuentra
`git status`; en una terminal, donde el usuario ya sabe lo que quiere teclear, es un intercambio
razonable, y el menú sigue estando ahí para explorar.

### ADR-015 — Los perfiles se guardan en userData, no en el repositorio del usuario
**Fecha:** 2026-08-23
**Contexto:** Un perfil "Backend + Web" es configuración de solución. Podría vivir en un archivo
dentro del repositorio (como hace `.vs/` o `.idea/`) o fuera.
**Decisión:** `userData/startup-profiles.json`, con la ruta del workspace como clave.
**Consecuencias:** el IDE no crea archivos dentro del proyecto de nadie, que es la clase de cosa que
acaba en un commit ajeno o en una discusión sobre el `.gitignore`. A cambio, los perfiles no se
comparten con el equipo: para eso ya existe `launchSettings.json`, que es el mecanismo del
ecosistema y que el IDE ya lee (iteración 10). Los perfiles que apuntan a un `.csproj` que ya no
existe se limpian al cargar, así que renombrar un proyecto no deja un botón de Play roto.

---

### Iteración 11 — 2026-08-23 — Fase 9: selector de inicio y terminal asistida
**Objetivo:** cerrar la distancia con Visual Studio y Rider en las dos cosas que más se usan y que
faltaban: decidir qué se arranca desde la barra superior, y una terminal que ayude a escribir.

**Módulo 1 — Selector de inicio.**
- `src/shared/startup.ts`: modelo puro (proyecto ejecutable, perfil, modo) y las reglas que deciden
  qué se arranca y cómo. Sin dependencias, así que lo comparten el proceso principal, el renderer y
  las pruebas.
- `src/main/services/startup-service.ts`: persistencia por workspace, tolerante a archivos
  corruptos y con limpieza de proyectos desaparecidos.
- `src/renderer/views/startup-bar.ts`: el control de la barra superior —desplegable de proyectos y
  perfiles, conmutador Depurar / Sin depurar, Play y Stop— y el modal multiproyecto con casillas,
  reordenación y perfiles con nombre.
- Canales de salida por proceso en `panel.ts`: cada proyecto arrancado tiene su pestaña con su
  nombre, un punto de estado y el puerto en el que escucha, clicable para abrirlo.
- Contratos nuevos: `startup:get`, `startup:save`, `git:branches` y `label` en
  `DotnetTaskRequest`/`DotnetTaskStarted`.

**Módulo 2 — Terminal asistida.**
- `src/renderer/terminal-suggest.ts`: motor puro de sugerencias para git y la CLI de .NET, con
  ramas y proyectos reales inyectados como contexto.
- `git-service.listBranches()`: ramas locales y remotas ordenadas por fecha de commit, con caché de
  15 s porque el autocompletado consulta en cada pulsación.
- Texto fantasma en línea con indicador de `Tab`, menú navegable con las flechas y aceptación con
  Tab o flecha derecha. Con el menú abierto las flechas navegan sugerencias; con él cerrado siguen
  siendo el historial.

**Errores encontrados:**
- *Síntoma:* el heredoc volvió a comerse las contrabarras y `output.split(/\r?\n/)` llegó a
  `git-service.ts` como un CR y un LF literales dentro del regex.
  *Causa raíz:* la trampa ya documentada en `CLAUDE.md`, esta vez con dos capas (bash y node -e).
  *Arreglo:* todos los parches de esta iteración se escribieron como archivos `.mjs` y se
  ejecutaron con node, sin pasar el código por la shell. El regex quedó con `String.raw`.
- *Síntoma:* el menú de sugerencias aparecía cortado por arriba: con el panel bajo de altura, las
  primeras entradas —justo la que acepta el tabulador— quedaban fuera de la vista.
  *Causa raíz:* `max-height` fija en CSS, sin relación con el hueco real sobre el prompt.
  *Arreglo:* la altura se calcula al pintar, a partir de la distancia entre el prompt y el borde
  superior del panel. Verificado con `--probe=`: el menú empieza 10 px por debajo del panel.
- *Síntoma:* el canal de un proyecto enseñaba el puerto HTTP y no el del perfil (HTTPS).
  *Causa raíz:* Kestrel anuncia las dos URLs y el código se quedaba con la última.
  *Arreglo:* se conserva la primera, que es la del perfil de `launchSettings.json`, la misma que
  abre `dotnet run`.
- *Observado en esta iteración, corregido en la siguiente:* al arrancar con un workspace reciente
  ya borrado, el proceso principal registraba un `ENOENT` en la consola. Ver iteración 12.

**Verificado sobre la aplicación real** (solución hexagonal `Ph` con Web API + Blazor, net10.0),
midiendo con `--ui=` y `--probe=` en vez de mirar capturas:
- Barra superior: `{"picker":"Adapters.Blazor","modes":["Depurar*","Sin depurar"],"play":true}`.
- Desplegable: lista los dos adaptadores conductores y la entrada "Configurar varios proyectos…".
- Modal: las dos casillas, el orden y los botones de guardar.
- **Arranque multiproyecto real**: tras marcar los dos proyectos y pulsar Play en modo "Sin
  depurar", el panel mostró `["Compilación","Adapters.Blazor","Adapters.Web"]`, la pestaña Salida
  con la insignia `2` y dos botones "Detener Adapters.Blazor" / "Detener Adapters.Web".
- **Puertos**: con los servidores ya levantados,
  `Adapters.Blazor:5587` y `Adapters.Web:5585`, enlazando a `https://localhost:5587` y
  `https://localhost:5585` — exactamente los del `launchSettings.json` generado.
- Terminal: escribiendo `git `, el fantasma dice `git status` con la tecla `Tab` y el menú lista
  los subcomandos con su descripción.
- `npm test` en verde de punta a punta y `--smoke-test` → `SMOKE_OK`.


### Iteración 12 — 2026-08-23 — El historial de recientes deja de mentir
**Síntoma:** en cada arranque, el proceso principal escribía en el log
`Error occurred in handler for 'workspace:open': ENOENT: no such file or directory, stat '...'`.
La aplicación arrancaba bien, pero además la pantalla de bienvenida seguía ofreciendo carpetas
borradas como si se pudieran abrir.

**Causa raíz:** eran tres fallos encadenados, no uno.
1. El renderer reabría `recentWorkspaces[0]` a ciegas. No puede hacer otra cosa: no tiene acceso al
   disco, así que no sabía si esa carpeta seguía existiendo.
2. `workspace:open` no validaba nada. Llamaba a `setWorkspaceRoot(directory)` —moviendo la raíz del
   guardián de rutas a una carpeta inexistente— y dejaba que el ENOENT saliera de `loadSolution`
   sin traducir. Electron registra toda excepción que sale de un handler: de ahí el ruido.
3. La bienvenida pintaba el historial tal cual, sin distinguir lo que existe de lo que no.

**Hecho:**
- `src/main/services/workspace-recents.ts`: `isOpenableWorkspace` (existe **y** es directorio),
  `describeRecents` (anota disponibilidad sin borrar nada) y `firstAvailable`. Node puro y probado
  con carpetas reales.
- `openWorkspaceDirectory` valida **antes** de tocar el estado: si la ruta no sirve, ni se mueve la
  raíz del guardián ni se recarga nada, y el mensaje dice qué ha pasado y qué hacer. La ruta de
  línea de comandos (`dotforge-ide <carpeta>`) tenía el mismo agujero y usa ahora el mismo criterio.
- Canales nuevos `workspace:recents` y `workspace:open-recent`. Reabrir "lo último" pasa a ser una
  decisión del proceso principal, que es quien conoce el disco: elige el reciente más nuevo que
  **todavía exista** y devuelve `null` si no queda ninguno. Sin intentos condenados, sin ruido.
- La bienvenida marca los no disponibles como entradas apagadas y sin acción, con el texto
  "no disponible".
- 12 pruebas nuevas en `tests/unit/workspace-recents.test.mjs`, con carpetas y archivos de verdad.

**Decisión que conviene recordar:** no se borra del historial lo que no está disponible. Es
tentador —dejaría la lista siempre limpia— pero un proyecto en un USB desconectado o en una unidad
de red caída desaparecería para siempre por haber arrancado el IDE sin el disco puesto. Se enseña
apagado, que informa sin destruir.

**Verificado** con el caso real que lo destapó: las tres entradas del historial de esta máquina
apuntaban a carpetas borradas.
- Antes: `ENOENT` en el log en cada arranque.
- Ahora: ni `ENOENT` ni `Error occurred in handler` en la salida, y el probe devuelve
  `[{"texto":"Phno disponible","readonly":true,"esBoton":false}, …]` para las tres.
- Camino bueno intacto: tras abrir una solución real, arrancar sin argumentos la reabre sola
  (`{"title":"Ok.Shop","disponibles":1}`).
- `npm test` en verde (329 pruebas unitarias) y `--smoke-test` → `SMOKE_OK`.

**Versión:** el arreglo del historial de recientes es una corrección de comportamiento sobre la
1.3.0, sin funcionalidad nueva ni cambios de contrato para el usuario, así que por semver le
corresponde el tercer número: **1.3.1**. Los canales `workspace:recents` y `workspace:open-recent`
son internos —superficie IPC, no API pública— y existen sólo para poder hacer la corrección.

### ADR-016 — El prompt de sistema lo compone el proceso principal, no el renderer
**Fecha:** 2026-08-23
**Contexto:** El asistente promete algo concreto: responder respetando la arquitectura del proyecto
abierto. Esa promesa se cumple o se incumple en un sitio muy pequeño —el prompt de sistema— y
había que decidir quién lo escribe.
**Opciones:**
- (a) El renderer compone el prompt completo y lo manda por IPC. Es lo más directo: la vista ya
  tiene el archivo, la selección y los diagnósticos.
- (b) El renderer manda contexto y mensajes; el proceso principal compone el prompt.
**Decisión:** (b). El renderer envía `AiContext` y la lista de mensajes; `systemPrompt()` se ejecuta
en el proceso principal en cada petición, y `register.ts` **sobrescribe** la arquitectura y el mapa
de proyectos con los de la solución realmente abierta en vez de fiarse de lo que llegue.
**Consecuencias:** las reglas de arquitectura dejan de ser un parámetro de la interfaz y pasan a ser
parte del contrato del asistente. Un fallo del renderer —o una página comprometida, que es el
escenario contra el que existe todo el aislamiento de esta app— no puede pedir "ignora las reglas":
el validador descarta los roles que no son `user` ni `assistant`, así que un `system` inyectado
desde el renderer no llega a ninguna parte. El coste es que el renderer no puede afinar el prompt;
a cambio, lo que se le impone al modelo se lee entero en un único archivo probado.

### ADR-017 — HTTP directo para los tres proveedores, sin SDK
**Fecha:** 2026-08-23
**Contexto:** Hay tres proveedores (Anthropic, OpenAI y Ollama) y cada uno tiene su SDK oficial o
su cliente recomendado.
**Opciones:**
- (a) Un SDK por proveedor. Tipos oficiales, reintentos y helpers de streaming ya resueltos.
- (b) El SDK de Anthropic para Anthropic y `fetch` para los otros dos.
- (c) `fetch` para los tres, con un constructor de peticiones y un parser de streaming por formato.
**Decisión:** (c).
**Consecuencias:** (b) queda descartada de entrada: mezclar un SDK con llamadas HTTP crudas dentro
del mismo módulo da lo peor de las dos cosas —dos modelos de error, dos formas de cancelar y dos
sitios donde mirar cuando algo falla—. Entre (a) y (c) pesa el empaquetado: un IDE de escritorio
carga esto en el proceso principal de Electron y tres SDK son tres árboles de dependencias que hay
que auditar, actualizar y firmar. Con (c), la superficie es un archivo que construye una petición y
otro que la parsea, los dos funciones puras y por tanto probables sin red ni claves — que es
justamente lo que permite las 46 aserciones de `ai-providers.test.mjs`. El precio es real y conviene
anotarlo: cuando un proveedor cambie su formato de streaming, el aviso no llegará por un `npm
outdated`, llegará por un fallo. Por eso el parser está probado con troceado arbitrario y por eso
los errores HTTP se traducen a mensajes accionables en vez de propagarse crudos.

### ADR-018 — Modelos de la generación actual por defecto, los anteriores como opción
**Fecha:** 2026-08-23
**Contexto:** La especificación de la fase pedía "Claude 3.7 Sonnet / Claude 3.5 Haiku" y
"GPT-4o / o3-mini". Los dos modelos de Claude citados son de la generación anterior; la actual es
la familia Claude 5 (Opus 5, Sonnet 5) más Haiku 4.5, y su API tiene diferencias que no son
cosméticas: `temperature` y `budget_tokens` están retirados —devuelven 400— y el esfuerzo se
controla con `output_config.effort` junto a razonamiento adaptativo.
**Decisión:** el catálogo ofrece las dos generaciones. El valor por defecto es `claude-opus-5`, y
`claude-3-7-sonnet-latest` y `claude-3-5-haiku-latest` quedan marcados como `legacy: true` y se
enseñan en el desplegable con el sufijo "· anterior".
**Consecuencias:** quien tenga una clave con acceso limitado, o quiera reproducir un resultado
antiguo, sigue pudiendo elegirlos; quien no toque nada arranca con lo mejor disponible. La
diferencia de API se resuelve con un flag por modelo (`supportsEffort`) en vez de con una cadena de
`if` por versión: a un modelo antiguo no se le manda `output_config` ni `thinking`, y a ninguno se
le manda nunca `temperature` ni `budget_tokens`. Hay una prueba por cada una de esas tres reglas,
porque el fallo sería un 400 en mitad de una conversación y no un error de compilación.

### ADR-019 — Sin cifrado del sistema, la clave no toca el disco
**Fecha:** 2026-08-23
**Contexto:** Las claves de API se guardan con `safeStorage`, que delega en DPAPI (Windows) y
Keychain (macOS). En algún entorno —una sesión de Linux sin llavero— `isEncryptionAvailable()`
devuelve false.
**Opciones:** (a) guardar la clave en claro en `userData` avisando en la interfaz, (b) no guardarla
y usarla sólo durante la sesión, (c) no permitir configurar el proveedor en ese caso.
**Decisión:** (b). La clave se queda en memoria, el archivo `ai-credentials.json` ni se crea, y el
handler devuelve un estado con el motivo, que la interfaz enseña.
**Consecuencias:** el usuario tiene que volver a pegar la clave en cada arranque en ese entorno
concreto, lo cual es molesto y se le dice claramente. La alternativa (a) es la que acaba, años
después, con una clave de producción en el perfil de alguien y en una copia de seguridad que nadie
recordaba. (c) sería peor que el problema: el asistente dejaría de existir en esa máquina.

---

### Iteración 13 — 2026-08-23 — Fase 10: DotForge AI Assistant
**Objetivo:** que el IDE entienda de la arquitectura del proyecto abierto y pueda ayudar sin
romperla — que es lo único que un asistente genérico no puede hacer.

**Módulo 1 — Proveedor y transporte.**
- `src/shared/ai.ts`: catálogo de proveedores y modelos, preferencias y tipos del streaming. Sin
  dependencias, así que lo comparten proceso principal, renderer y pruebas.
- `src/main/services/ai/request-builder.ts` y `stream-parser.ts`: funciones puras que construyen la
  petición de cada proveedor y parsean su respuesta (SSE con tipos en Anthropic, SSE con `[DONE]`
  en OpenAI, NDJSON en Ollama).
- `ai-service.ts`: un `AbortController` por `requestId`, temporizador de inactividad de 90 s y
  traducción de todos los fallos a mensajes accionables. La fuente de credenciales se **inyecta**
  (`setCredentialSource`), así que el cliente entero no depende de Electron y se puede ejercitar
  contra un servidor de mentira.
- `secret-store.ts`: claves cifradas con `safeStorage`, con la política del ADR-019.
- Canales nuevos: `ai:status`, `ai:set-key`, `ai:probe`, `ai:send`, `ai:cancel` y los eventos
  `event:ai-delta` / `event:ai-end`.

**Módulo 2 — Contexto RAG y reglas de arquitectura.**
- `src/shared/ai-context.ts`: detección de la arquitectura (manifiesto `dotforge.json` primero,
  forma de la solución después), mapa de proyecto a capa, recorte por ventana del archivo activo y
  composición del prompt de sistema con las reglas de Clean, Hexagonal o DDD.
- Las cuatro piezas del contexto —archivo, selección, arquitectura y diagnósticos— se pueden apagar
  por separado desde los ajustes, y hay una prueba de que apagarlas surte efecto de verdad.

**Módulo 3 — Interfaz.**
- `views/ai-chat.ts`: sexto icono en la barra de actividad y panel de chat con respuesta token a
  token, bloques de código con "Copiar" y "Aplicar", y acciones rápidas.
- `views/ai-inline.ts`: `Ctrl+I` sobre la selección, con vista previa de diferencias — el cambio se
  aplica al modelo de Monaco y se resalta, y el widget enseña lo que desaparece y el recuento.
- `views/ai-diff.ts` (en `shared/ai-diff.ts`): extracción del bloque de código, reindentación al
  hueco de la selección y diferencia por subsecuencia común más larga.
- Acciones en el menú contextual del editor y del árbol de archivos, entradas en la paleta y un
  menú nativo "IA".

**Errores encontrados:**
- *Síntoma:* un archivo de 48.000 caracteres en **una sola línea** llegaba entero al prompt pese al
  recorte.
  *Causa raíz:* `windowAround` recortaba por líneas, y una línea más larga que todo el presupuesto
  no se puede recortar por líneas.
  *Arreglo:* tope duro sobre la ventana ya calculada. Lo destapó la prueba, no un usuario.
- *Síntoma:* `coerceChatRequest` aceptaba un `requestId` de 80 caracteres recortándolo a 64.
  *Causa raíz:* recortar por costumbre. Un id truncado es válido pero ya no casa con el que espera
  el renderer, así que los deltas irían a una conversación que no los reclama.
  *Arreglo:* se valida sin recortar; un id largo se rechaza.
- *Síntoma:* la suite pasaba en verde y tardaba **cinco minutos** en salir.
  *Causa raíz:* la prueba de cancelación deja adrede una respuesta HTTP sin cerrar, y `server.close()`
  espera al `requestTimeout` del servidor, que por defecto son 300 s.
  *Arreglo:* `closeAllConnections()` antes de cerrar. De 302 s a 302 ms.
- *Síntoma (evitado a tiempo):* `Ctrl+Shift+I` para abrir el asistente chocaba con el inspector de
  Electron, y `Ctrl+I` registrado a la vez en el menú nativo y en `window` abría el widget dos veces.
  *Arreglo:* el atajo del panel es `Ctrl+Shift+A`, y `Ctrl+I` se atiende sólo desde el menú nativo,
  cuyo acelerador llega antes que el renderer.

**Verificado sobre la aplicación real**, con `--ui=` y `--probe=` en vez de mirar capturas:
- Barra de actividad: `["Explorador de soluciones","Generador de arquitecturas","Paquetes NuGet",
  "Depuración y pruebas","DotForge AI Assistant","Ajustes"]`.
- Panel de IA: título `DotForge AI`, estado `Falta la clave de API de Anthropic. [Configurar]` y
  acciones rápidas `["Explicar","Pruebas xUnit","Revisar arquitectura"]` — es decir, sin clave el
  asistente lo dice y ofrece el camino, en vez de fallar al primer mensaje.
- Ajustes: el grupo "Asistente de IA" con proveedor, modelo, endpoint, clave, longitud, esfuerzo y
  los cuatro interruptores de contexto; el desplegable lista `Claude Opus 5`, `Claude Sonnet 5`,
  `Claude Haiku 4.5`, `Claude 3.7 Sonnet · anterior` y `Claude 3.5 Haiku · anterior`.
- **Conversación real de punta a punta** contra un servidor que habla el protocolo de Ollama
  (`tests/unit/ai-streaming.test.mjs`): el texto llega en varios deltas, el cierre trae el consumo
  de tokens, el prompt de sistema que sale por el cable contiene las reglas de la arquitectura
  detectada, el contexto viaja sólo en el último turno, un 401 se traduce a "clave de API", un
  endpoint apagado a "comprueba que Ollama está en marcha" y cancelar cierra la conexión.
- `npm test` en verde de punta a punta: **596 pruebas** (442 unit, 41 security, 57 package, 56
  scaffold), de las cuales 113 son nuevas del módulo de IA. `--smoke-test` → `SMOKE_OK`.
- Empaquetado real: `npm run dist:win` → `DotForge IDE-1.4.0-Setup-x64.exe` (117,3 MB) y
  `DotForge IDE-1.4.0-win-x64.zip` (161,6 MB); la poda liberó los 278,9 MB de la 1.3.1 antes de
  empaquetar y `verify:dist` termina sin problemas (sin firmar, como corresponde sin certificado).

**Versión:** el módulo de IA es funcionalidad nueva, con contratos IPC nuevos y sin romper nada de
lo anterior, así que por semver le corresponde el segundo número: 1.3.1 → **1.4.0** (ADR-009).

---

### ADR-020 — El control de fuentes invoca `git`, no una librería de JavaScript
**Fecha:** 2026-08-23
**Contexto:** El panel necesita estado, diffs y operaciones de escritura sobre el repositorio.
**Opciones:**
- (a) `isomorphic-git`: implementación pura en JS, sin binario externo.
- (b) `nodegit`: enlaces nativos a libgit2; hay que compilarlos por plataforma.
- (c) Invocar el `git` del sistema con `execFile` y un array de argumentos.
**Decisión:** (c) el `git` del sistema.
**Consecuencias:** worktrees, submódulos, `core.autocrlf`, hooks, credential helpers, HEAD
desprendido y repositorios sin commits funcionan **igual que en la terminal del usuario**, porque
es literalmente el mismo programa. No se añade ninguna dependencia ni ningún binario al paquete, y
el servicio no importa `electron`, así que se puede probar contra un repositorio real con Node
pelado. A cambio, sin git instalado el panel dice que no hay repositorio en vez de funcionar a
medias — que es la respuesta honesta.

### ADR-021 — El editor de diferencias usa modelos propios y es de sólo lectura
**Fecha:** 2026-08-23
**Contexto:** Al pulsar un archivo del panel hay que enseñar una comparación lado a lado.
**Opciones:**
- (a) Reutilizar el modelo `file:` del archivo como lado derecho: se edita en el diff y se guarda.
- (b) Crear dos modelos nuevos con un esquema propio (`dotforge-diff:`) y bloquear la edición.
**Decisión:** (b), con una pestaña propia por comparación (`git:<sección>:<ruta>`).
**Consecuencias:** editar dentro del diff no ensucia la pestaña del archivo ni manda cambios al
servidor de lenguaje de un documento que nadie ha abierto, y el mismo archivo puede estar abierto
a la vez como "lo preparado" y como "lo que falta por preparar", que son dos comparaciones
distintas. El precio: para editar hay que abrir el archivo, a un doble clic de distancia.

### ADR-022 — La verbosidad la decide el proceso principal y se traduce por verbo
**Fecha:** 2026-08-23
**Contexto:** Un solo ajuste debe gobernar `build`, `run`, `watch`, `test`, `clean`, `restore`,
`format` y la sesión de depuración.
**Decisión:** el nivel se guarda en preferencias, lo lee **el proceso principal** al lanzar cada
tarea —el renderer no puede elegirlo, igual que con el prompt del asistente (ADR-016)— y una
función pura (`verbosityPlan`) decide qué argumento le corresponde a cada verbo y en qué posición.
**Consecuencias:** `dotnet watch` recibe `--verbose` **antes** del subcomando y nunca
`--verbosity`, porque todo lo que va después se lo pasa a la aplicación hija; el resto recibe
`--verbosity <nivel>` detrás del objetivo. El nivel se escribe siempre, incluso `minimal`, para que
el comando que aparece en la salida diga la verdad. Y "recopilar todas las excepciones" no es una
bandera de MSBuild: son variables de entorno (`Logging__LogLevel__*`, `ASPNETCORE_DETAILEDERRORS`,
`COREHOST_TRACE`), que viven en la misma función para que nivel y comportamiento no se separen.

### ADR-023 — Una herramienta desactivada se atenúa, no desaparece
**Fecha:** 2026-08-23
**Contexto:** Al apagar el asistente en Ajustes, ¿qué pasa con su icono de la barra de actividad?
**Opciones:** (a) quitarlo de la barra, (b) dejarlo igual y fallar al pulsarlo, (c) atenuarlo,
bloquear la navegación y explicar en el tooltip dónde se enciende.
**Decisión:** (c).
**Consecuencias:** quien apagó el asistente hace tres semanas puede volver a encontrarlo; quien lo
pulsa no acaba en un panel roto ni en un error. La regla vive en una función pura
(`aiEntryState`) que usan la barra, la paleta y el asistente en línea, de modo que el interruptor
significa lo mismo en los tres sitios. Se aplica igual a cualquier herramienta futura que se pueda
desactivar.

### ADR-024 — `pull --ff-only` y confirmación nombrando la consecuencia
**Fecha:** 2026-08-23
**Contexto:** Dos operaciones del panel pueden dejar el repositorio en un estado que el usuario no
esperaba: traer cambios y descartar cambios.
**Decisión:** `pull` se ejecuta siempre con `--ff-only`, y descartar pide confirmación diciendo
explícitamente qué va a pasar con **estos** archivos.
**Consecuencias:** una fusión o un rebase automáticos disparados por un botón son la forma más
rápida de dejar a alguien con un conflicto que no sabe de dónde ha salido; si no se puede avanzar,
el panel lo dice y deja la decisión en la terminal. Y como "descartar" significa restaurar un
archivo con seguimiento pero **borrar** uno sin rastrear, la confirmación distingue los dos casos
y cuenta cuántos hay de cada uno, en vez de un "¿estás seguro?" genérico.

---

### Iteración 14 — 2026-08-23 — Fase 11: Git visual, procesos visibles y logs de .NET
**Objetivo:** cerrar las tres cosas que obligaban a salir del IDE —ver qué has cambiado, ver qué
tienes corriendo y ver por qué algo no arranca— y hacer que el interruptor del asistente signifique
algo en la interfaz.

**Módulo 1 — Panel de control de código fuente.**
- `src/shared/git.ts`: modelo puro. Parseo de `git status --porcelain --branch` con renombrados,
  conflictos, rutas entrecomilladas, HEAD desprendido y "No commits yet"; resumen de
  sincronización; y la construcción de la petición de diferencias (qué lado sale de HEAD, cuál del
  índice y cuál del disco).
- `src/main/services/git-service.ts`: el servicio entero. Estado detallado con caché corta,
  preparar, quitar de preparados, descartar, commit (con enmienda), push con `--set-upstream`
  automático la primera vez, pull, sync, cambio y creación de rama, y contenido de cada lado del
  diff. Todo con `execFile` y array de argumentos, y con `GIT_TERMINAL_PROMPT=0` para que un
  remoto que pide credenciales falle en vez de colgar el IDE.
- `src/renderer/views/git.ts`: la vista. Secciones colapsables, letras `M`/`A`/`D`/`U`, acciones al
  pasar el ratón (`+`, `-`, `↩`), caja de mensaje con `Ctrl+Enter`, botones Commit/Push/Pull/Sync
  con contadores `↑n ↓m` y selector de rama con creación incluida.
- Editor de diferencias lado a lado en el hueco del editor, con pestaña propia y cierre.

**Módulo 2 — Procesos visibles.**
- La barra superior pinta una pastilla por proceso arrancado, con su color de estado y su puerto;
  un clic enfoca su canal y un clic en el puerto abre la aplicación en el navegador.
- Cada canal de salida gana una cabecera con el nombre del proyecto, su insignia de tipo (Web API,
  Blazor, CLI…), el estado, el enlace HTTPS y botones para reiniciar o detener **sólo ese** proceso.

**Módulo 3 — Verbosidad de la CLI de .NET.**
- Ajuste nuevo con los cuatro niveles y su traducción a argumentos y variables de entorno
  (ADR-022), aplicada también al entorno del proceso que lanza el depurador.

**Módulo 4 — Estado del asistente de IA.**
- `src/renderer/ai-availability.ts` y ADR-023: icono atenuado, sin navegación y con el mensaje
  "El asistente de IA está deshabilitado. Puedes activarlo desde la configuración".

**Errores encontrados y solucionados:**
1. *Síntoma:* `commit` con el índice vacío devolvía "El commit ha fallado" en vez de "no hay nada
   preparado".
   *Causa raíz:* la detección buscaba `nothing to commit` en la salida de git, y en un Windows en
   español git responde en español. Una regex sobre mensajes traducidos es una bomba de relojería.
   *Arreglo:* se decide mirando el índice **antes** de llamar a git. Lo destapó la prueba contra un
   repositorio real (`tests/unit/git-service.test.mjs`), no un usuario.
2. *Síntoma:* la acción de diagnóstico `--ui=` no hacía nada al arrancar con una solución abierta.
   *Causa raíz:* pulsaba a los 3,2 s fijos, y con un workspace abierto la interfaz todavía está
   cargando Monaco y leyendo la solución: el control aún no existía. Sin error, sin aviso y sin
   efecto — el peor tipo de fallo.
   *Arreglo:* `--ui-wait=<ms>` para la pulsación y `--wait=<ms>` para la medida o la captura.
3. *Síntoma (evitado):* la fila de archivo llamaba a `openFile` con la ruta **relativa** al
   repositorio.
   *Causa raíz:* la raíz del repositorio no tiene por qué ser la carpeta abierta (un monorepo, o
   abrir una subcarpeta).
   *Arreglo:* la raíz viaja dentro del estado (`GitRepositoryStatus.root`) y la vista compone la
   ruta absoluta con ella.
4. *Síntoma:* añadir el icono de control de fuentes rompió `--ui=settings`, `--ui=ai` y compañía.
   *Causa raíz:* esas acciones pulsan por índice posicional dentro de `.activity-item`.
   *Arreglo:* índices actualizados y el orden de la barra escrito en un comentario justo encima,
   para que la próxima herramienta que se añada no vuelva a romperlos en silencio.
5. *Aviso del entorno:* en Windows, `core.autocrlf` devuelve el archivo restaurado con CRLF aunque
   el blob esté en LF. Comparar byte a byte en la prueba comprobaba la configuración de git del
   equipo, no el servicio: se normaliza antes de comparar.

**Verificado sobre la aplicación real** (con `--ui=`, `--probe=` y una solución generada de verdad):
- Panel de git sobre este mismo repositorio: `{"title":"Control de código fuente","branch":"master",
  "sections":["Cambios preparados","Cambios"],"counts":["0","27"]}`, con la letra correcta por
  archivo.
- Comparación abierta desde el panel: `diffVisible: true`, pestaña
  `debug-controller.ts (Índice ↔ Local)` y dos modelos `dotforge-diff:` de 313 y 333 líneas — el
  lado izquierdo sale del índice y el derecho del disco.
- Perfil multiproyecto de una solución hexagonal generada al vuelo (net10.0, Web + Blazor):
  pastillas `Adapters.Web:5585` y `Adapters.Blazor:5587` en verde y cabecera de canal
  `Adapters.Blazor · Blazor · En ejecución · https://localhost:5587`.
- Verbosidad en `detailed`: el comando que aparece en la salida es
  `❯ dotnet watch --verbose --project …`, no `--verbosity detailed` — que es justo lo que exige la
  CLI de watch.
- Asistente apagado desde Ajustes: `class="activity-item disabled"`, `aria-disabled="true"`,
  `opacity: 0.38`, el tooltip exacto y el clic sin efecto (`blocked: true`); al volver a
  encenderlo, el icono recupera su comportamiento normal.
- `npm test` en verde de punta a punta: **694 pruebas** (540 unit, 41 security, 57 package, 56
  scaffold), de las cuales 98 son nuevas de esta fase. `--smoke-test` → `SMOKE_OK`.
- Empaquetado real: `npm run dist:win` → `DotForge IDE-1.5.0-Setup-x64.exe` (117,3 MB) y
  `DotForge IDE-1.5.0-win-x64.zip` (161,6 MB); la poda liberó los 279,0 MB de la 1.4.0 antes de
  empaquetar y `verify:dist --require win` termina sin problemas (sin firmar, como corresponde sin
  certificado).

**Versión:** funcionalidad nueva, con contratos IPC nuevos y sin romper nada de lo anterior:
1.4.0 → **1.5.0** (ADR-009).

---

### ADR-025 — El esquema se deduce de las migraciones; el IDE no se conecta a la base de datos
**Fecha:** 2026-08-23
**Contexto:** El panel de datos tiene que enseñar tablas y columnas. La forma obvia es conectarse
a la base de datos y leer su catálogo.
**Opciones:** (a) conectar de verdad, con un driver por motor (SQL Server, PostgreSQL, MySQL,
SQLite); (b) pedírselo a `dotnet ef dbcontext info`, que sólo da el proveedor y la cadena;
(c) leer los archivos de migración del repositorio y aplicar sus operaciones en orden.
**Decisión:** (c), y decirlo en el propio panel: el rótulo es "Esquema deducido".
**Consecuencias:** cero dependencias nativas (la regla del proyecto), cero credenciales pedidas al
usuario y funciona con la base de datos apagada, que es el estado normal a media mañana. A cambio,
lo que se ve es el esquema **según el repositorio**, no según el servidor, y una migración que
ejecuta `migrationBuilder.Sql(...)` es opaca: se cuenta aparte y el panel avisa de cuántas hay.
Es un análisis de texto de C# generado por herramientas, no de C# escrito a mano, así que la
gramática que hay que cubrir es pequeña y estable.

### ADR-026 — El cliente HTTP usa `node:http`, y el certificado autofirmado sólo vale en localhost
**Fecha:** 2026-08-23
**Contexto:** Enviar la petición de un archivo `.http` contra una API en desarrollo. `fetch` está
disponible en el proceso principal y sería lo natural.
**Decisión:** `node:http` / `node:https`, con `rejectUnauthorized: false` **únicamente** cuando el
host es `localhost`, `127.0.0.1` o `::1`.
**Consecuencias:** el certificado de desarrollo de ASP.NET Core es autofirmado y `fetch` lo rechaza
sin que el usuario pueda hacer nada desde el IDE; probar la propia API acabaría siendo imposible.
Al acotar la excepción a la máquina local, un certificado inválido en un host remoto sigue siendo
un error —que es lo correcto— y la excepción no se puede ampliar desde el renderer, porque la
decisión se toma en el proceso principal a partir de la URL ya parseada. De propina se ganan los
redireccionamientos seguidos a mano con tope y aviso de la URL final, y un tiempo medido que
distingue "no ha respondido" de "ha respondido un 500".

### ADR-027 — Las lentes de código de endpoints se calculan por texto, no por el LSP
**Fecha:** 2026-08-23
**Contexto:** Para pintar "Probar GET /api/products" sobre un endpoint hay que saber dónde están
los endpoints. Roslyn lo sabe con exactitud.
**Decisión:** análisis de texto acotado (`src/shared/api-endpoints.ts`), no una consulta al LSP.
**Consecuencias:** la lente aparece mientras se escribe, con el servidor de lenguaje arrancando,
degradado o apagado, y en archivos que todavía no compilan — que es justo cuando se está
escribiendo un endpoint. El precio es equivocarse de vez en cuando, y se elige equivocarse **de la
forma barata**: ofrecer una prueba de más nunca rompe nada, mientras que no ofrecer ninguna hace
invisible la funcionalidad. Se cubren las dos formas que existen hoy (Minimal API con `MapGroup` y
controladores con `[Route("api/[controller]")]`), y cada una tiene sus pruebas.

---

### Iteración 15 — 2026-08-23 — Fase 12: EF Core visual y cliente HTTP
**Objetivo:** quitar las dos razones que quedaban para abrir una terminal o un Postman: gestionar
migraciones y probar un endpoint.

**Módulo 1 — Gestor de Entity Framework Core.**
- `src/shared/efcore.ts`: modelo puro. Extracción del bloque `//BEGIN … //END` que las herramientas
  de EF envuelven alrededor de su JSON, migraciones con su estado y su fecha, contextos,
  construcción de argumentos por operación y lectura de cadenas de conexión de un `appsettings.json`
  con comentarios y comas colgantes (que los tiene, siempre).
- `src/shared/efcore-schema.ts`: tablas y columnas deducidas de las migraciones (ADR-025), con un
  lector de paréntesis equilibrados que respeta las cadenas de C#, claves primarias simples y
  compuestas, índices, y `AddColumn`/`DropColumn`/`RenameTable` aplicados en orden.
- `src/main/services/efcore-service.ts`: lectura con `execFile` (el panel necesita el resultado) y
  escritura con `spawn` por el canal de tareas (el panel necesita ver qué pasa durante dos minutos).
- `src/renderer/views/efcore.ts`: panel con selector de proyecto y de proyecto de arranque, lista de
  migraciones aplicadas/pendientes, esquema navegable y cadenas de conexión con la contraseña tapada.

**Módulo 2 — Cliente HTTP integrado.**
- `src/shared/http-file.ts`: parser del formato `.http`/`.rest` con separadores `###`, variables
  `@nombre = valor`, variables dinámicas y resolución con dobles llaves.
- `src/renderer/languages/http.ts`: gramática Monarch del lenguaje `http`.
- Lente "Enviar petición" sobre cada bloque y pestaña "HTTP" en el panel inferior con estado,
  tiempo, tamaño, cuerpo reindentado, cabeceras e historial de las últimas 20.
- `src/shared/api-endpoints.ts` + lente sobre cada endpoint de C# que genera —**añadiendo**, nunca
  sobrescribiendo— la petición en el `.http` del proyecto, con la URL base tomada del proceso que
  esté corriendo si lo hay.

**Errores encontrados y solucionados:**
1. *Síntoma (evitado a tiempo):* la primera versión de la gramática entraba en un estado `url` tras
   el verbo y lo cerraba con una regla de fin de línea.
   *Causa raíz:* los estados de Monarch **sobreviven al salto de línea**; una regla de longitud cero
   al final de la línea no llega a evaluarse, así que el estado no se cerraba nunca y todas las
   cabeceras siguientes se pintaban como URL.
   *Arreglo:* una sola regla por línea de petición, con grupos de captura. Sin estados, sin fuga.
2. *Síntoma:* el panel enseñaba "Could not execute because the specified command or file was not
   found." sin decir qué hacer.
   *Causa raíz:* es el mensaje de `dotnet` cuando la herramienta `dotnet-ef` no está instalada, y se
   estaba propagando tal cual.
   *Arreglo:* si la CLI falla **y no ha llegado a emitir su bloque JSON**, se añade la orden de
   instalación. Es una decisión de estado, no una regex sobre un mensaje traducido (misma lección
   que el `nothing to commit` de la iteración anterior).
3. *Síntoma:* `el bundle del renderer no incrusta Monaco` se puso en rojo al añadir dos vistas.
   *Causa raíz:* la prueba usaba un tope absoluto de 400 KB como proxy de "Monaco no está dentro";
   el renderer creció legítimamente hasta 415 KB.
   *Arreglo:* la prueba ahora comprueba lo que dice comprobar — que el bundle es un orden de
   magnitud más pequeño que la carpeta `vendor/monaco` que dice no incrustar — y deja un tope
   absoluto de cordura muy por encima.
4. *Síntoma:* los botones del panel enseñaban "Actualizar ...", "Quitar la ú...".
   *Causa raíz:* la barra lateral mide 240 px y tres botones con rótulo no caben.
   *Arreglo:* un botón con rótulo corto y dos de icono con la frase entera en el `title`.

**Verificado sobre la aplicación real** (solución `Acme.Shop` generada al vuelo con `--db sqlite`):
- `--ui=efcore`: el panel elige solo `Acme.Shop.Infrastructure` como proyecto con migraciones y
  `Acme.Shop.WebApi` como proyecto de arranque, y lista las tres secciones. Sin `dotnet-ef`
  instalado en esta máquina, el aviso incluye la orden de instalación, que es el comportamiento
  buscado.
- `--ui=http` sobre un `.http` real: resaltado correcto de separador, verbo, URL, cabeceras y cuerpo
  JSON; lente "Enviar petición" sobre cada bloque; pestaña HTTP en el panel; el archivo aparece en
  el explorador con su icono propio y la barra de estado dice `http`.
- El envío de verdad se comprueba en la suite: cinco pruebas contra un servidor levantado en el
  propio test (cuerpo, cabeceras, redirección 301, 404 y puerto cerrado).
- `npm test` en verde de punta a punta: **776 pruebas** (622 unit, 41 security, 57 package, 56
  scaffold), de las cuales 82 son nuevas de esta fase. `prune:dist` liberó los 279,0 MB de la 1.5.0
  y `verify:dist` termina sin problemas.

**Versión:** funcionalidad nueva con contratos IPC nuevos, sin romper nada anterior:
1.5.0 → **1.6.0** (ADR-009).

---

### ADR-028 — El registro se parsea por formato, no por regex sobre palabras traducidas
**Fecha:** 2026-08-23
**Contexto:** El visor de registro tiene que entender la salida de una aplicación .NET real, que
mezcla en el mismo flujo la consola de `Microsoft.Extensions.Logging` (arranque del host), Serilog
(cuando toma el control) y, si alguien lo configuró, NLog o JSON compacto.
**Decisión:** un parser por formato, todos probados con capturas reales, y **ninguna decisión
basada en una palabra traducible**. En particular, un marco de pila se reconoce por su forma
—firma de método, ruta que acaba en `.cs` y número al final— y no por las palabras `at` y `line`,
que en un Windows en español son `en` y `línea`.
**Consecuencias:** el visor funciona en cualquier idioma del sistema y con los cuatro formatos
mezclados en la misma salida. Lo que no encaja con ningún formato **sigue apareciendo** como
evento de nivel informativo: un visor que se come la mitad de la salida es peor que no tener
visor. Es la tercera vez que este proyecto tropieza con lo mismo (los mensajes de git, el de
`dotnet ef`), y por eso está escrito como decisión y no como comentario.

### ADR-029 — El linter de arquitectura calla ante la duda
**Fecha:** 2026-08-23
**Contexto:** El linter clasifica cada proyecto en una capa por su nombre. ¿Qué hace con
`Acme.Shop.Utilidades`, que no encaja en ninguna?
**Opciones:** (a) asignarle la capa más parecida; (b) tratarlo como parte del núcleo y ser
estricto; (c) dejarlo sin clasificar y no decir nada sobre él.
**Decisión:** (c). Y lo mismo con una solución cuya arquitectura no se reconoce: cero avisos.
**Consecuencias:** el linter nunca denuncia lo que no entiende, que es la única forma de que la
gente no lo apague el primer día. El precio es que un proyecto con un nombre poco convencional se
queda sin vigilar; se prefiere ese fallo al contrario. Los avisos son **siempre `warning`**, nunca
`error`: una violación de arquitectura no impide compilar, y pintarla en rojo junto a los errores
reales del compilador enseñaría a ignorar los dos. Y viven en su propio propietario de marcadores
de Monaco, para que una compilación correcta no los borre: el código compila y sigue rompiendo la
regla.

### ADR-030 — El contexto del autocompletado se pide entero y de una vez
**Fecha:** 2026-08-23
**Contexto:** Sugerir contenedores de Docker, imágenes y scripts de `package.json` obliga a salir
del renderer, que no puede ejecutar nada.
**Decisión:** un único canal (`terminal:context`) que devuelve todo resuelto, invocado al abrir una
solución y al mostrar la terminal — **nunca por pulsación de tecla**.
**Consecuencias:** el motor de sugerencias sigue siendo una función pura sin E/S, que es lo que
permite probarlo entero con Node pelado. Cada llamada lanza un `docker ps`, así que atarlo a las
pulsaciones habría significado un proceso por tecla. A cambio, la lista puede quedar unos segundos
desactualizada si se levanta un contenedor desde fuera del IDE; se resuelve volviendo a abrir la
terminal, y es un precio bajo comparado con la alternativa.

---

### Iteración 16 — 2026-08-23 — Fase 13: registro, linter de arquitectura y terminal en la nube
**Objetivo:** que las tres preguntas que obligan a salir del IDE —"¿qué ha pasado?", "¿esto rompe
la arquitectura?" y "¿cómo se llamaba ese comando?"— se respondan dentro.

**Módulo 1 — Visor de registro estructurado.**
- `src/shared/log-events.ts`: parser de los cinco formatos que salen de una solución .NET sin
  configurar nada (Serilog con plantilla corta y con marca completa, la consola de
  `Microsoft.Extensions.Logging` a dos líneas, NLog y CLEF), con las trazas pegadas al evento que
  las provocó y los marcos reconocidos por su forma (ADR-028).
- Pestaña **Registro** en el panel inferior: pastillas por nivel con su cuenta, filtro de texto,
  detalle desplegable por evento y marcos de pila **clicables** que abren el `.cs` en su línea.
- El repintado va con freno de 400 ms: una aplicación arrancando escupe cientos de líneas por
  segundo y repintar por cada una haría imposible pulsar en un marco.

**Módulo 2 — Linter de reglas de arquitectura.**
- `src/shared/architecture-rules.ts`: las reglas que el asistente sabe explicar en prosa, ahora
  comprobables. Tres vías: referencias entre proyectos (`DF1001`), `using` prohibidos con su línea
  (`DF1002`) y paquetes de infraestructura dentro del núcleo (`DF1003`).
- Se ejecuta al abrir o recargar la solución y al guardar un `.cs`. Los avisos van al panel de
  problemas y al margen del editor, en su propio propietario de marcadores (ADR-029).

**Módulo 3 — Terminal: Docker, Azure y npm.**
- `src/shared/docker.ts` + `docker-service.ts`: estado del motor leído con `--format "{{json .}}"`,
  con puertos publicados deduplicados (IPv4 e IPv6 son el mismo puerto) y las etiquetas de Compose
  ya interpretadas.
- Sugerencias nuevas: subcomandos de `docker` y `docker compose`, **contenedores reales** tras
  `docker logs`/`exec`/`stop`, **imágenes locales** tras `docker run`, los grupos de `az` que usa
  un desarrollador .NET (`webapp`, `group`, `sql`, `acr`, `containerapp`) y los **scripts del
  `package.json` de este repositorio** tras `npm run`.
- `az` entra en la lista blanca de la terminal: publicar la API que se acaba de escribir es parte
  del mismo flujo.

**Errores encontrados y solucionados:**
1. *Síntoma:* el visor de registro enseñaba `[HH:mm:ss INF] Application started` — con la hora
   literal — en una solución recién generada.
   *Causa raíz:* **la plantilla de scaffolding estaba mal desde la v1.1**: el `outputTemplate` de
   Serilog escribía `[HH:mm:ss {Level:u3}]` en vez de `[{Timestamp:HH:mm:ss} {Level:u3}]`, así que
   todas las soluciones generadas registraban la misma hora falsa en cada línea. Nadie lo había
   visto porque el resto de la línea era correcto.
   *Arreglo:* corregido en las seis plantillas y añadida una prueba que lo vigila
   (`tests/unit/blueprints.test.mjs`). Es exactamente el tipo de fallo que sólo aparece cuando una
   herramienta nueva mira de verdad lo que produce la anterior.
2. *Síntoma:* el marco de pila `at Servicio.CreateAsync(CreateProduct command) in C:\…\S.cs:line 42`
   devolvía como archivo `command) in C:\…\S.cs`.
   *Causa raíz:* el patrón buscaba "algo, espacio, algo, espacio, ruta", y los argumentos del
   método tienen espacios. Además una ruta de Windows trae sus propios dos puntos (`C:\`), que un
   patrón poco anclado confunde con el separador `:line`.
   *Arreglo:* se ancla al **último paréntesis** de la firma, que es lo único estable, y la ruta se
   exige terminada en una extensión de código.
3. *Síntoma:* `SuggestionKind` creció y la etiqueta del menú de sugerencias dejó de compilar.
   *Causa raíz:* `Record<SuggestionKind, string>` es exhaustivo a propósito.
   *Arreglo:* añadidas las tres etiquetas nuevas. El tipo hizo su trabajo: el fallo apareció al
   compilar y no en la interfaz.

**Verificado sobre la aplicación real** (solución `Acme.Logs` generada y ejecutada de verdad):
- `--ui=startup-logs`: la aplicación arranca y el visor enseña **93 eventos** con la hora real
  (`23:39:46`), 33 de nivel informativo y el resto de depuración, con las pastillas de nivel
  contando cada una.
- Violación de arquitectura introducida a mano en el `.csproj` del dominio y leída con `--probe=`:
  `DF1001 Acme.Logs.Domain referencia a Acme.Logs.Infrastructure: Dominio no puede depender de
  Infraestructura en una arquitectura Clean. — Acme.Logs.Domain.csproj:1:1`, con la insignia `1` en
  la pestaña de problemas.
- `npm test` en verde de punta a punta: **856 pruebas** (702 unit, 41 security, 57 package, 56
  scaffold), de las cuales 80 son nuevas de esta fase.

**Versión:** funcionalidad nueva, un canal IPC nuevo y una corrección en las plantillas generadas:
1.6.0 → **1.7.0** (ADR-009).

---

### ADR-031 — El compose manda, el motor confirma
**Fecha:** 2026-08-23
**Contexto:** El panel de contenedores puede construirse de dos formas: listando lo que el motor
tiene corriendo, o listando lo que el proyecto declara y pegándole el estado real.
**Decisión:** la lista sale del `docker-compose.yml` del repositorio; el motor sólo aporta el
estado de cada servicio.
**Consecuencias:** el panel **sirve con todo apagado**, que es justo cuando hace falta: enseña qué
necesita este proyecto para arrancar y da el botón para levantarlo. Al revés estaría vacío
precisamente en ese momento. La correspondencia entre servicio y contenedor se hace por la
etiqueta `com.docker.compose.service` y, en segundo lugar, por el `container_name` declarado;
**nunca por parecido del nombre**, porque dos proyectos con un servicio `redis` acabarían
intercambiándose los botones de parar. Los contenedores que no pertenecen al compose se listan
aparte, sin mezclarlos: son de otro trabajo. La regla entera vive en una función pura
(`matchComposeState`) y está probada con los casos que importan.

### ADR-032 — Parser propio de YAML para el subconjunto de Compose
**Fecha:** 2026-08-23
**Contexto:** Leer un `docker-compose.yml` exige un parser de YAML.
**Opciones:** (a) añadir `js-yaml` o `yaml` como dependencia de runtime; (b) escribir el
subconjunto que usa Compose.
**Decisión:** (b), con los límites escritos en la cabecera del archivo.
**Consecuencias:** el proyecto mantiene su regla de dependencias mínimas y auditables, y el
subconjunto —mapas anidados, listas en bloque y en línea, escalares con comillas y comentarios—
cabe en un archivo con 31 pruebas. Lo que no se soporta (anclas, bloques literales, documentos
múltiples) se degrada perdiendo detalle, nunca fallando entero: sin esas piezas la lista de
servicios sigue saliendo. El caso borde que más costó no es exótico: `- "5672:5672"` lleva dos
puntos y **no** es un mapa, es un puerto; distinguirlo exige mirar qué viene después de los dos
puntos, no si los hay.

### ADR-033 — Docker apagado no vacía el panel
**Fecha:** 2026-08-23
**Contexto:** Sin Docker instalado o con el motor parado, ¿qué enseña el panel de contenedores?
**Decisión:** los servicios declarados, con sus acciones deshabilitadas y un aviso arriba que dice
qué pasa y qué hacer.
**Consecuencias:** es la misma regla que con el asistente de IA apagado (ADR-023): una herramienta
que no está disponible se atenúa y se explica, no desaparece. Quien abre el panel con el motor
parado descubre igualmente qué necesita el proyecto —SQL Server, Redis, RabbitMQ y sus puertos—,
que es la mitad del valor de la vista.

---

### Iteración 17 — 2026-08-23 — Fase 14: contenedores y Docker Compose
**Objetivo:** que "levantar la base de datos antes de pulsar F5" sea un botón y no un viaje a otra
ventana.

**Módulo único — Panel de contenedores.**
- `src/shared/compose.ts`: parser propio del subconjunto de YAML que usa Compose (ADR-032),
  modelo de servicio (imagen o `build`, `container_name`, puertos, dependencias, perfiles) y
  construcción de los comandos de `docker compose` y de contenedor.
- `matchComposeState`: el cruce entre lo declarado y lo que corre (ADR-031), como función pura.
- `docker-service.ts`: búsqueda de archivos de Compose en la raíz y un nivel por debajo, lectura
  del archivo y ejecución transmitida por el canal de tareas, igual que EF Core.
- `src/renderer/views/containers.ts`: sexta herramienta de la barra de actividad. Cabecera con el
  archivo, el recuento `n/m arriba` y los botones Levantar / Bajar / Registro; una fila por
  servicio con su punto de estado, su icono, su nombre real ("SQL Server", no la imagen), sus
  puertos y las acciones al pasar el ratón (arrancar, parar, reiniciar, registro). Los contenedores
  ajenos al compose, en una sección aparte.
- Los puertos de lo que se abre en un navegador (Seq, RabbitMQ, MailHog) son un enlace; los de una
  base de datos, no: abrir `http://localhost:1433` no lleva a ninguna parte.

**Seguridad.** Los tres canales nuevos validan lo que llega del renderer: la ruta del compose pasa
por el guardián del workspace **y** tiene que llamarse como un archivo de Compose —sin lo segundo
sería un lector de archivos arbitrarios disfrazado—, y los nombres de servicio y de contenedor se
acotan a lo que Docker admite antes de entrar en un `argv`.

**Errores encontrados y solucionados:**
1. *Síntoma:* los puertos de un servicio salían como `[{ '"5672': '5672"' }]`.
   *Causa raíz:* el parser trataba `- "5672:5672"` como un mapa porque contenía dos puntos.
   *Arreglo:* una clave de YAML exige que tras los dos puntos venga un espacio o el fin de línea, y
   que el elemento no empiece por comilla. Con eso, un puerto vuelve a ser un puerto.
2. *Síntoma (evitado):* el panel se vaciaba entero al no encontrar Docker.
   *Causa raíz:* el estado del motor gobernaba todo el pintado.
   *Arreglo:* ADR-033. El compose se pinta igual; lo que se apaga son los botones.
3. *Decisión de diseño revisada:* la lógica de correspondencia entre servicios y contenedores
   estaba dentro de la vista, donde no se podía probar sin un Docker delante. Se sacó a
   `matchComposeState`, que es pura y tiene ocho pruebas propias — incluida la de los dos proyectos
   con un servicio `redis` cada uno.

**Verificado sobre la aplicación real:**
- `--ui=containers` con un `docker-compose.yml` de cuatro servicios y **sin Docker instalado**: el
  panel enseña el aviso "Docker no está instalado o no está en el PATH", el archivo,
  `0/4 arriba`, los botones atenuados y las cuatro filas con su nombre real y sus puertos
  (`sqlserver 1433`, `redis 6379`, `rabbitmq 5672, 15672`, `seq 5341`).
- En la misma captura siguen funcionando las dos funcionalidades de la iteración anterior: la
  barra de estado marca `⚠ 1` y la pestaña de problemas la insignia `1` del aviso de arquitectura.
- `npm test` en verde de punta a punta: **887 pruebas** (733 unit, 41 security, 57 package, 56
  scaffold), de las cuales 31 son nuevas de esta fase. `prune:dist` y `verify:dist` terminan sin
  problemas sobre la 1.8.0.

**Versión:** funcionalidad nueva con cinco canales IPC nuevos, sin romper nada anterior:
1.7.0 → **1.8.0** (ADR-009).

---

### ADR-034 — El proceso depurado es un proceso más
**Fecha:** 2026-08-24
**Contexto:** Un perfil multiproyecto en modo depuración arranca el primero con el depurador y el
resto como tareas. Los segundos tenían canal propio, pastilla, puerto y botón de parada; el
primero no tenía nada de eso, porque su salida no venía de una tarea sino de eventos del depurador
y llegaba sin `taskId`.
**Decisión:** el proceso depurado abre su canal **antes** de arrancar, como cualquier otro, y su
salida se dirige explícitamente a él (`appendDebugOutput`). El canal se marca `isDebug`, lo que le
da su propio botón de parada —que llama a `debug:stop` en vez de cancelar una tarea— y su estado
propio ("Depurando" en vez de "En ejecución").
**Consecuencias:** desaparece el canal "Compilación :5013", que era el síntoma más confuso: el
canal de compilación anunciaba el puerto de una aplicación. Además el proceso depurado gana lo que
ya tenían los demás: pastilla en la barra superior (con icono de bug), enlace a su URL, reinicio
—que vuelve a **depurar**, no a ejecutar sin depurador— y parada individual.

---

### Iteración 18 — 2026-08-24 — v1.8.1: el proceso depurado deja de esconderse en "Compilación"

**Reportado por el usuario**, con dos capturas: al lanzar un perfil `Blazor + WebApi` en modo
depuración, la barra de canales enseñaba `Compilación :5013` y `WebApi :5011`, y a la derecha un
botón `Detener WebApi` con un spinner girando para siempre. Invirtiendo el orden del perfil, los
papeles se intercambiaban — que es exactamente la pista que confirmó el diagnóstico: **el que se
descolocaba era siempre el primero, que es el que se depura** (ADR-012: una sola sesión).

**Causa raíz (1).** `onDebugOutput` llamaba a `panel.append(text, stream)` sin `taskId`, y ese
camino termina en el canal de compilación. Con él se colaba también la detección de la URL, así que
el puerto de la aplicación depurada acababa pegado al canal "Compilación".

**Causa raíz (2), descubierta al verificar el arreglo.** Abrir el canal del depurado no bastaba:
`debug:start` **empieza parando** la sesión anterior, y ese `stop` emite `idle` **antes** de
arrancar. El manejador cerraba el canal en cualquier `idle`, así que lo mataba recién abierto y la
salida volvía a "Compilación". La regla correcta —un `idle` sólo cierra si antes hubo sesión, un
`error` cierra siempre— vive ahora en `debugChannelTransition`, que es pura y tiene seis pruebas.

**Causa raíz (3).** El spinner permanente. La barra de pestañas pintaba un spinner junto a
"Detener X" para toda tarea viva. Un spinner promete que algo va a terminar; una Web API arrancada
no va a terminar. Ahora las tareas de larga duración (`run`, `watch`) llevan un punto verde —"esto
está en marcha"— y el spinner se reserva para lo que sí acaba: compilar, restaurar, probar.

**Cambios:**
- `Channel.isDebug` y `ServiceInfo.isDebug`: el canal sabe si lo gobierna el depurador.
- `startDebugChannel` / `appendDebugOutput` / `finishDebugChannel(ok)` en el panel.
- El paso `debug` del plan de arranque también llama a `registerService`, así que el proceso
  depurado tiene insignia de tipo y ruta de proyecto desde la primera línea.
- Botón de parada del canal habilitado para el depurado (llama a `debug:stop`), y botón propio en
  la barra de pestañas mientras la sesión viva.
- Reiniciar un proceso depurado vuelve a depurarlo en vez de relanzarlo como tarea suelta.
- **Por qué uno es distinto, dicho donde se ve:** icono de bug en su pastilla, estado "Depurando"
  en la cabecera de su canal, e insignia `depurado` sobre el primer proyecto del diálogo de
  perfiles cuando el modo es depuración — que es donde se decide el orden.

**Verificado sobre la aplicación real** (solución generada con `--ui both`, perfil
`Blazor + WebApi` en modo depuración):
- Barra superior: `● 🐞 Blazor` y `● WebApi`.
- Canales: `Compilación` (limpia, sin puerto), `● Blazor`, `● WebApi`.
- Cabecera del canal depurado: `Blazor · Blazor · ● 🐞 Depurando · https://localhost:5013`.
- Barra de pestañas: `● Detener WebApi` y `● Detener Blazor`, los dos con punto verde; ni un
  spinner. Comprobado además leyendo el píxel del indicador: `rgb(28, 122, 79)`.
- `npm test` en verde: **893 pruebas**, seis de ellas nuevas para la regla del canal depurado.

**Versión:** corrección de comportamiento visible, sin contratos nuevos: 1.8.0 → **1.8.1**.

### ADR-035 — La sintaxis es un código de colores, no una armonía
**Fecha:** 2026-08-24
**Contexto:** Desde la Fase 7 los colores de código se elegían dentro de un rango de saturación
estrecho, con el criterio de que ninguno "saltara" por encima del resto. El resultado era agradable
y decía poco: un tipo, un método y una variable local se distinguían por matices de azul.
**Opciones:**
- (a) mantener la paleta armónica y confiar en la forma del código para orientarse;
- (b) adoptar la jerarquía cromática de Visual Studio: verde azulado para los tipos, verde agua para
  las interfaces, dorado para lo que se invoca, azul claro para los miembros de datos, gris claro
  para lo local y púrpura para el flujo de control.
**Decisión:** (b), en los dos temas.
**Consecuencias:** el color deja de ser decoración y pasa a ser **información**: en veinte líneas de
configuración de un `Program.cs`, `WebApplication` se lee como tipo y `CreateBuilder` como llamada
sin tener que leerlas. A cambio la pantalla tiene más colores, y por eso cada uno se ha verificado
contra el fondo: el peor sobre `#1b1d27` es el comentario, con 4,93:1, por encima del mínimo AA. El
tema claro **no** usa los mismos hexadecimales: el azul de Visual Studio sobre blanco se queda en
3:1, así que cada familia tiene ahí su versión oscurecida.

### ADR-036 — Los resultados de las pruebas salen del TRX, no de la consola
**Fecha:** 2026-08-24
**Contexto:** `dotnet test` escribe por consola una línea por prueba con su estado, y es lo más fácil
de parsear. En un Windows en español esa línea dice `Con error` donde la documentación dice `Failed`.
**Decisión:** se ejecuta siempre con `--logger "trx;LogFileName=…"` y los resultados se leen del XML,
donde el estado es el nombre de una enumeración (`Passed`, `Failed`, `NotExecuted`) y no cambia con el
idioma del sistema. El parseo de la consola existe, se usa sólo si el TRX no está —el runner ha
reventado antes de escribirlo— y el resumen sale marcado como `degraded` para que la interfaz lo diga.
**Consecuencias:** es la misma decisión que con el bloque JSON de EF Core (ADR-025) y por el mismo
motivo. Además el TRX trae lo que la consola no da estructurado: la duración por prueba, el mensaje
del assert y la traza completa, que es lo que alimenta el panel de problemas. Dos detalles que
costaron una vuelta cada uno: el nombre bueno está en `TestDefinitions` y no en `testName` —en una
`[Theory]` ese campo trae los argumentos del caso—, y el TRX escribe los saltos de línea del mensaje
como `&#xD;&#xA;`, que hay que descodificar o aparecen incrustados en cada línea de la traza.

### ADR-037 — Las pruebas se descubren leyendo el código, no compilando
**Fecha:** 2026-08-24
**Contexto:** `dotnet test --list-tests` da la lista exacta, y para darla compila la solución entera.
**Decisión:** el árbol y las lentes salen de un análisis de texto de los `.cs` de los proyectos de
pruebas, igual que las lentes de endpoints (ADR-027).
**Consecuencias:** el árbol está lleno al abrir la solución y la lente aparece sobre el `[Fact]` que
se está escribiendo, en un archivo que todavía no compila. El precio es que una prueba generada por
un `[TestCaseSource]` exótico puede no aparecer hasta que se ejecute, y que se puede ofrecer ejecutar
algo que `dotnet test` dirá que no existe: el error barato. Se reconocen xUnit (`[Fact]`, `[Theory]`),
NUnit (`[Test]`, `[TestCase]`) y MSTest (`[TestMethod]`).

### ADR-038 — El monitor de contadores usa `collect`, no `monitor`
**Fecha:** 2026-08-24
**Contexto:** `dotnet-counters monitor` pinta una tabla en directo y parece la opción evidente para
un panel de métricas. Con la salida redirigida —que es la única forma de leerla desde el IDE—
revienta con una `NullReferenceException` antes de emitir un solo valor: necesita una consola de
verdad para calcular el ancho y mover el cursor.
**Decisión:** `dotnet-counters collect --format csv --output <archivo>`, y el servicio lee el archivo
de forma incremental, guardando el desplazamiento y procesando sólo hasta el último salto de línea.
**Consecuencias:** funciona sin terminal, sobrevive a que la herramienta esté escribiendo una fila
justo cuando se lee, y el CSV es un formato estable que además sirve para pegar una captura en una
prueba. El archivo vive en el directorio temporal y se borra al parar la sesión. De paso apareció lo
que de verdad importaba: **desde .NET 9 los contadores tienen otros nombres**. Los EventCounters
clásicos (`CPU Usage`, `GC Heap Size`) dan paso a las métricas del `Meter` de `System.Runtime`
(`dotnet.process.cpu.time`, `dotnet.gc.collections[gc.heap.generation=gen0]`), con unidad declarada y
etiquetas. Se soportan las dos familias: con sólo la primera el panel se quedaba vacío justo en el
framework que este IDE targetea.

### ADR-039 — A Roslyn hay que abrirle la solución
**Fecha:** 2026-08-24
**Contexto:** Al conectar el proveedor de tokens semánticos apareció que el servidor devolvía `null`.
Al comprobarlo, devolvía `null` **a todo**: hover, completado, símbolos. Y sin embargo el handshake
terminaba bien y la barra de estado decía "Roslyn LanguageServer listo".
**Causa:** `initialize` le dice al servidor dónde está la carpeta, pero no qué proyectos cargar. Su
espacio de trabajo se llena con dos notificaciones que **no son parte de LSP**: `solution/open` y
`project/open`. Sin ellas el servidor arranca, contesta al handshake y no sabe nada de ningún archivo.
**Decisión:** en cuanto termina el handshake se le abre la solución (o la lista de proyectos si no hay
`.sln`), y su stderr deja de tragarse: va a la consola del proceso principal.
**Consecuencias:** es el fallo más difícil de ver de este proyecto, porque por fuera parecía que
funcionaba. La regla que queda escrita es más general que el arreglo: **un servidor que responde
"listo" no está diciendo que sepa nada**, y un proveedor que devuelve siempre vacío es indistinguible
de uno que funciona si nadie mira el error. Por eso ahora se registra.

### ADR-040 — La versión del servidor de Roslyn se fija; no se elige sola
**Fecha:** 2026-08-24
**Contexto:** El feed `vs-impl` publica **763 versiones** de `Microsoft.CodeAnalysis.LanguageServer`
para `win-x64`, y **ninguna es estable en el sentido de SemVer**: todas llevan sufijo de
prelanzamiento, porque son las compilaciones internas con las que se sirven Visual Studio y la
extensión de C# de VS Code. Conviven bandas ya publicadas (`4.14.0-3.*`), la rama principal sin
publicar (`5.4.0-2.*`) y hasta compilaciones declaradas de prueba (`5.3.0-2-test.*`). Coger "la más
alta" —que es lo que hacía `pickLatestVersion`— significa coger cada día la compilación de anoche
de la rama principal de Roslyn, sin que nadie la haya ejecutado nunca contra este IDE.
**Decisión:** manda `ROSLYN_PINNED_VERSION`, hoy `4.14.0-3.26423.7`. "Verificada" significa que se ha
descargado, extraído y arrancado a mano, y que ha compuesto su gráfico MEF y contestado por stdio.
Si el feed dejara de publicarla, se coge la más alta que no declare marcadores de inestabilidad
(`test`, `preview`, `alpha`, `beta`, `rc`…), y sólo si no queda ninguna se acepta una de ésas antes
que dejar al usuario sin servidor. La selección devuelve también **por qué** eligió lo que eligió.
**Consecuencias:** el desempate no lo ganó el número más alto sino el `runtimeconfig.json`:
`4.14.0-3.26423.7` declara `net9.0` con `rollForward: Major`, así que arranca con el runtime 9 **o**
con el 10; las bandas 5.x declaran `net10.0` y dejarían sin servidor a quien tenga instalado justo
el .NET 9 que este IDE pide como mínimo. La versión fijada existe para los seis RID soportados,
comprobado contra el feed. El precio es que actualizarla es un cambio de código deliberado, con su
verificación a mano —que es exactamente lo que se quería—.

### ADR-041 — Una instalación se verifica archivo a archivo, no con un marcador
**Fecha:** 2026-08-24
**Contexto:** Este ADR nace de encontrar la causa real del fallo que la v1.9 dio por diagnosticado.
El IntelliSense de C# **nunca** funcionó en la máquina de desarrollo: Roslyn moría componiendo su
gráfico MEF con un `PartDiscoveryException` sobre `Microsoft.CodeAnalysis.CSharp.Features.dll`, y se
concluyó que el paquete del feed estaba roto. No lo estaba. El `.nupkg` es correcto, su SHA-256
coincide con el del feed y nuestro propio extractor lo descomprime bien cuando se le vuelve a pedir.
Lo que estaba mal era **un archivo de los 462 extraídos**, truncado en disco a 5.242.880 bytes
exactos —5 MiB clavados— cuando el ZIP declara 6.396.176. Extraído de nuevo, el mismo paquete y la
misma versión arrancan sin un solo `fail:`.
**Causa de que durase nueve versiones:** lo único que se guardaba tras extraer era un `.dotforge-ok`
con la versión y el SHA-256 **del `.nupkg` descargado**. Eso verifica el archivo que ya no está en
el disco y no dice una palabra de los 462 que sí están. Como el marcador decía "ok", nadie volvió a
mirar aquel directorio jamás.
**Decisión:** al extraer se escribe un manifiesto con **tamaño y hash de cada archivo**, y siempre
**el último**, para que una extracción interrumpida deje un directorio sin manifiesto —y un
directorio sin manifiesto se reinstala entero—. Hay dos comprobaciones con costes muy distintos: la
superficial (un `stat` por archivo, milisegundos) se hace en **cada arranque**; la profunda (releer y
hashear los ~250 MB) sólo cuando el servidor ya ha fallado. Además, el extractor se niega a escribir
un archivo cuyo inflate no mida lo que declara el directorio central, y la descarga comprueba
`content-length`.
**Consecuencias:** la comprobación barata es la que habría cazado esto el primer día. Las cachés de
la v1.9 y anteriores no tienen manifiesto, así que cuentan como no verificadas y se reinstalan solas
la primera vez que se abre la v2.0: el usuario no tiene que borrar nada a mano. Los archivos **de
más** no son un problema —el servidor escribe sus registros y cachés dentro de su directorio—.
**Aplica a todo el toolchain, no sólo al servidor de lenguaje.** NetCoreDbg se instalaba con el mismo
marcador, y ahí el fallo se manifestaría peor: un ensamblado de Roslyn truncado al menos deja un
`PartDiscoveryException` en el registro, mientras que un `netcoredbg.exe` cortado no da ningún error
legible —da una sesión de depuración que no arranca—. Los dos adquisidores pasan ahora por
`installArchive` / `verifyInstall`, y una prueba de seguridad comprueba que ninguno vuelva a
declararse un `MARKER` propio.

### ADR-042 — Un servidor roto se detecta por stderr y por nombre de tipo, nunca por el mensaje
**Fecha:** 2026-08-24
**Contexto:** Hacía falta decidir cuándo dar por muerto a Roslyn. El caso real es traicionero: el
servidor **no se cae** cuando MEF no compone. Escribe el error por stderr, sigue vivo, contesta al
handshake y anuncia "Language server initialized" por stdout. Lo que queda es un servidor que
responde `null` a todo con la barra de estado diciendo "listo".
**Decisión:** tres reglas. **(1)** Se mira stderr, no el código de salida —el proceso termina con 0—.
**(2)** Se buscan **nombres de tipo de excepción** (`PartDiscoveryException`, `TypeLoadException`,
`BadImageFormatException`…), nunca mensajes: el mensaje de este mismo fallo sale en español en un
Windows en español —"No se pudo cargar el ensamblado […] para su análisis"—, y el paquete trae trece
culturas. **(3)** El nombre sólo cuenta dentro de un bloque de nivel `fail:` o `crit:`, porque el
servidor registra por stderr cosas informativas que mencionan rutas que no existen. A eso se suma
que **un cierre que nadie ha pedido es un fallo aunque el código sea 0**, para el caso de la ADR-043.
**Consecuencias:** el escáner lleva búfer de líneas porque los trozos de un stream no respetan los
saltos: `PartDiscoveryEx` + `ception:` es una lectura perfectamente normal, y sin búfer el fallo se
detecta de forma intermitente, que es la peor forma de no detectarlo. Se prueba troceándolo carácter
a carácter. `OutOfMemoryException` queda deliberadamente fuera: habla de la máquina, no del paquete,
y vetar una versión por un pico de memoria dejaría ese equipo sin Roslyn para siempre.

### ADR-043 — A `workspace/configuration` se le contesta con un array, no con `null`
**Fecha:** 2026-08-24
**Contexto:** Con la instalación ya sana y la versión fijada, Roslyn seguía sin servir: cargaba, decía
"listo" y a los pocos segundos se apagaba con código 0, sin una línea en stderr. Reproducido con un
cliente LSP mínimo fuera del IDE, el diálogo es claro: al abrir la solución el servidor pide
`workspace/configuration` con treinta y tantas secciones de opciones
(`csharp|completion.dotnet_show_name_completion_suggestions` y compañía), su handler hace
`Contract.ThrowIfNull` sobre la respuesta, levanta `InvalidOperationException: Unexpected null`,
escribe "Error processing queue, shutting down" y se despide.
**Causa:** en LSP el tráfico va en los dos sentidos, y esto se olvida porque el 99 % de los mensajes
salen del editor. DotForge contestaba `null` a **toda** petición del servidor, con el razonamiento
correcto —no dejarlo bloqueado— y una respuesta que para ésta es inválida.
**Decisión:** lo que se contesta lo decide `src/shared/lsp-protocol.ts`, que es puro. A
`workspace/configuration` se le devuelve un array con **una entrada por elemento pedido**, con valor
`null` en cada una: significa "no tengo configurado eso, usa tu valor por defecto", que es
exactamente la verdad. El resto de peticiones siguen con `null`, que para ellas es su respuesta
correcta (`client/registerCapability`, `window/workDoneProgress/create`,
`workspace/_roslyn_projectNeedsRestore`).
**Consecuencias:** con esto la solución carga sus cinco proyectos, llega
`workspace/projectInitializationComplete` y `textDocument/semanticTokens/full` empieza a devolver
datos. Lo que importa del array es el **tamaño**: el servidor empareja secciones y respuestas por
posición. Y la lección general, que es la tercera de la misma familia en este proyecto: **contestar
algo no es contestar bien**, y un servidor que se apaga limpiamente puede estar diciendo que se le ha
contestado mal.

### ADR-044 — Cuarentena por versión y RID, con indulto si la culpa era de la copia
**Fecha:** 2026-08-24
**Contexto:** Cuando Roslyn falla en marcha hay que hacer dos cosas: dar servicio ya —OmniSharp— y
no repetir mañana el mismo intento. Pero "no repetir" exige saber **de quién era la culpa**, y las
dos causas se ven igual desde fuera (el mismo `PartDiscoveryException`) y se arreglan al revés: una
copia corrupta se borra y se vuelve a bajar; una compilación mala se veta. Vetar una versión buena
por un archivo que se truncó al escribirlo dejaría ese equipo sin Roslyn para siempre —que es justo
lo que la v1.9 estuvo a punto de dejar escrito en el código—.
**Decisión:** ante un fallo se audita la instalación entera, hash a hash (ADR-041). Si sale corrupta,
se **borra** la copia y se le **levanta el veto** a la versión. Si sale íntegra, la culpa es de la
compilación y la versión entra en cuarentena, anotada por RID: que esté rota para `win-x64` no dice
nada de `osx-arm64`, y el archivo viaja si el usuario sincroniza su perfil. En los dos casos se
conmuta a OmniSharp en el momento y el motivo aparece en la barra de estado.
**Consecuencias:** la cuarentena tiene tope de 50 entradas, porque es una lista de fallos y no un
historial. El selector de la ADR-040 la lee como lista de vetados, así que un equipo con una
compilación rota baja solo a la siguiente candidata en el arranque siguiente, sin intervención.

---

### Iteración 19 — 2026-08-24 — Fase 15: pruebas, color, túneles, métricas y seguridad

**Objetivo:** cerrar el hueco entre "el IDE compila y ejecuta" y "el IDE me dice cómo va": qué
pruebas fallan, qué es cada símbolo del código, cuánto está gastando la aplicación, qué paquetes
tienen avisos y cómo abrir el puerto local a un webhook.

**Cinco módulos, todos con su modelo puro aparte:**

- `src/shared/semantic-tokens.ts` — la codificación relativa de LSP y la normalización de los
  nombres de clasificación de Roslyn (`class name`, `keyword - control`, `xml doc comment - text`)
  a un conjunto pequeño de ámbitos con significado visual.
- `src/shared/test-explorer.ts` — descubrimiento de pruebas por texto, árbol, filtros de VSTest y
  lectura de resultados; `src/main/services/test-service.ts` recorre el disco y lanza `dotnet test`.
- `src/shared/dev-tunnel.ts` — argumentos de `devtunnel` y `ngrok`, y el escáner que reconoce la URL
  pública con búfer de líneas.
- `src/shared/perf-counters.ts` — las dos generaciones de nombres de contador, las transformaciones
  (bytes a MB, segundos de CPU a por ciento) y la geometría del gráfico.
- `src/shared/nuget-audit.ts` — el JSON de `dotnet list package --vulnerable` y la tabla degradada.

**Errores encontrados y solucionados:**

1. *Síntoma:* el resaltado semántico no pintaba nada aunque el servidor dijera "listo".
   *Causa raíz (1):* las listas `tokenTypes` y `tokenModifiers` de las capacidades del cliente iban
   **vacías** desde la Fase 2. Para LSP eso significa "no entiendo ningún tipo de token", así que un
   servidor correcto no manda ninguno.
   *Causa raíz (2):* aun con las capacidades bien, Roslyn seguía devolviendo `null` — y no sólo a los
   tokens: a hover, a completado y a símbolos. Le faltaba la notificación `solution/open` (ADR-039).
   *Arreglo:* las dos cosas, más registrar el stderr del servidor para que un fallo así no vuelva a
   ser invisible.
2. *Síntoma:* con el proveedor registrado, un archivo abierto se quedaba con los colores de la
   gramática aunque el servidor cargara después.
   *Causa raíz:* Monaco pide los tokens **una vez** por versión del documento; si la respuesta llega
   vacía no vuelve a preguntar hasta que se escriba en el archivo.
   *Arreglo:* el proveedor expone `onDidChange` y se dispara al llegar la leyenda y al recibir
   `workspace/projectInitializationComplete`.
3. *Síntoma:* el panel de métricas no enseñaba nada con una sesión en marcha.
   *Causa raíz:* `dotnet-counters monitor` revienta con la salida redirigida (ADR-038).
   *Arreglo:* `collect --format csv` leyendo el archivo de forma incremental.
4. *Síntoma:* con eso arreglado, el panel seguía vacío contra una Web API en net10.0.
   *Causa raíz:* .NET 9 sustituyó los EventCounters por el `Meter` de `System.Runtime`, con nombres
   nuevos, unidades declaradas y etiquetas.
   *Arreglo:* la tabla de contadores reconoce las dos familias y declara qué transformación necesita
   cada una. Las generaciones del GC se distinguen por su etiqueta, no por el nombre.
5. *Síntoma:* la traza de una prueba fallida aparecía con `&#xD;` incrustado en cada línea.
   *Causa raíz:* el parser de XML traduce las entidades con nombre, no las referencias numéricas, y
   el TRX escribe los saltos de línea como `&#xD;&#xA;`.
   *Arreglo:* descodificación explícita, con su prueba.
6. *Síntoma:* la primera visita a la pestaña de métricas decía "sin procesos .NET" con tres
   corriendo.
   *Causa raíz:* el panel se pinta al pulsar su pestaña, y ahí todavía no se había preguntado nada.
   *Arreglo:* la primera pintada dispara la consulta.
7. *Decisión de herramienta:* `--probe=` envuelve ahora la expresión en `Promise.resolve`. Sin eso no
   se puede medir nada asíncrono —una llamada IPC, una petición al servidor de lenguaje— porque
   serializar una promesa imprime `{}`. Es lo que permitió diagnosticar el punto 1.

**Verificado sobre la aplicación real** (solución `Acme.Lab` generada con el propio scaffolding,
net10.0, con su Web API arrancada):

- Explorador de pruebas: **13 pruebas descubiertas** en dos clases sin compilar nada; `Ejecutar
  todas` deja `12 correctas · 1 con error · 0 omitidas`, la prueba rota en rojo con
  `Assert.Equal() Failure: Strings differ / Expected: "Teclado roto" / Actual: "Teclado mecánico"`,
  su traza con `ProductTests.cs:line 15`, insignia `1` sobre el icono de pruebas y `1` en la pestaña
  de problemas.
- Colores: con datos de clasificación, `WebApplication` se pinta `rgb(78, 201, 176)` (#4EC9B0) y
  `CreateBuilder` `rgb(220, 220, 170)` (#DCDCAA), leídos del estilo calculado, no de una captura.
- Métricas: `Monitorizando Acme.Lab.WebApi`, grupos Proceso / Memoria / Recolección de basura y —con
  tráfico— HTTP; `Montón administrado 26 MB`, `Conjunto de trabajo 130 MB`, `Reserva 0,9 MB/s` y diez
  gráficos de tendencia.
- Auditoría: sobre la solución limpia, "Sin vulnerabilidades conocidas"; tras añadir
  `Newtonsoft.Json 12.0.1`, cinco filas `Alta` con `GHSA-5CRP-9R3C-P9VR`, marcando cuál es directa y
  cuáles transitivas, e insignia `5` sobre el icono de NuGet.
- Túnel: sin herramienta instalada, `▲ No hay ninguna herramienta de túnel instalada. Instala una:
  winget install Microsoft.devtunnel · winget install ngrok.ngrok`.
- `npm test` en verde de punta a punta: **1058 pruebas** (904 unit, 41 security, 57 package, 56
  scaffold), de las cuales 165 son nuevas de esta fase. `prune:dist` liberó los artefactos de la
  1.8.0 y `verify:dist` confirma el instalador y el ZIP de la 1.9.0.

**Limitación conocida, con diagnóstico.** En esta máquina el servidor de Roslyn arranca, contesta al
handshake y muere al componer su gráfico MEF:
`PartDiscoveryException: Could not find assembly Microsoft.CodeAnalysis.CSharp.Features, Version=5.4.0.0 … in any extension context`.
Se reproduce lanzando el ejecutable a mano, fuera del IDE, y no depende de la ruta ni de la caché de
composición. Es un fallo del paquete `microsoft.codeanalysis.languageserver.win-x64 5.4.0-2.26179.14`
del feed `dotnet-tools`, anterior a esta fase, y por eso el IntelliSense de C# nunca ha devuelto
datos en este equipo. Todo lo que depende del IDE está hecho y verificado —capacidades, leyenda,
descodificación, proveedor y colores— y el resaltado semántico se enciende solo el día que el
servidor conteste. Fijar una versión conocida buena del servidor queda anotado para la Fase 16.

**Versión:** funcionalidad nueva con once canales IPC nuevos y una corrección de comportamiento
visible en el resaltado: 1.8.1 → **1.9.0** (ADR-009).

---

### Iteración 20 — 2026-08-24 — Fase 16: el IntelliSense de C# funciona

**Objetivo:** cerrar la "limitación conocida" que arrastraba la v1.9 —el servidor de Roslyn arranca
y no sirve para nada— fijando una versión estable verificada y garantizando el respaldo automático
a OmniSharp cuando el servidor falle.

**Lo primero fue descubrir que el diagnóstico anterior era falso.** La v1.9 cerró con esta frase:
*"Es un fallo del paquete `microsoft.codeanalysis.languageserver.win-x64 5.4.0-2.26179.14` del feed
`dotnet-tools`"*. No lo era, y comprobarlo costó cuatro medidas:

1. Se reprodujo el `PartDiscoveryException` lanzando el ejecutable a mano. Se confirma.
2. Se leyó el tamaño del ensamblado señalado: **5.242.880 bytes**. Cinco mebibytes clavados es una
   cifra que no sale de un compilador; sale de un archivo cortado.
3. Se descargó el `.nupkg` del feed y se leyó su directorio central: esa entrada declara
   **6.396.176 bytes**. Y el SHA-256 del paquete recién bajado coincide **exactamente** con el que
   el marcador `.dotforge-ok` guardó el día que se instaló. El paquete siempre estuvo bien.
4. Se volvió a extraer y se lanzó el servidor: compone su gráfico MEF y contesta **sin un solo
   `fail:`**. Misma versión, mismo paquete, otra copia en disco.

De los 462 archivos extraídos, exactamente **uno** había quedado truncado, y el marcador de
instalación —que sólo guardaba el hash del `.nupkg`, un archivo que ya no está en el disco— decía
"ok" desde entonces. Ése es el fallo que dejó el IntelliSense de C# muerto desde la Fase 2.

**Y con eso arreglado, el servidor seguía sin servir.** Cargaba, decía "listo" y a los pocos
segundos se apagaba **con código 0 y sin una línea en stderr**. Reproducido con un cliente LSP
mínimo de 120 líneas escrito para esto, apareció la segunda causa: Roslyn pide
`workspace/configuration` al abrir la solución, DotForge contestaba `null` a toda petición del
servidor, y su handler responde a ese `null` rompiendo su cola de mensajes y despidiéndose
(ADR-043).

**Cinco decisiones, cinco ADR:**

- **ADR-040** — la versión se fija (`4.14.0-3.26423.7`) en vez de coger la más alta de las 763 del
  feed, que es la compilación de anoche de la rama principal de Roslyn.
- **ADR-041** — la instalación se verifica archivo a archivo contra un manifiesto con tamaño y hash,
  barata en cada arranque y profunda tras un fallo.
- **ADR-042** — un servidor roto se detecta por stderr y por nombre de tipo de excepción, nunca por
  el mensaje, que viene traducido.
- **ADR-043** — a `workspace/configuration` se le contesta con un array del tamaño pedido.
- **ADR-044** — una versión que falla queda en cuarentena por RID, salvo que la auditoría demuestre
  que la culpa era de la copia y no de la compilación.

**Errores encontrados y solucionados:**

1. *Síntoma:* el IntelliSense de C# nunca devolvió nada en este equipo.
   *Causa raíz:* un DLL truncado en disco que ninguna comprobación volvía a mirar (ADR-041).
   *Arreglo:* manifiesto por archivo, verificación en cada arranque y reinstalación automática. Las
   cachés de versiones anteriores no tienen manifiesto, así que se reinstalan solas.
2. *Síntoma:* con la copia sana, el servidor se apagaba con código 0 a los pocos segundos de decir
   que estaba listo.
   *Causa raíz:* `workspace/configuration` contestada con `null` (ADR-043).
   *Arreglo:* un array con una entrada por sección pedida.
3. *Síntoma:* ese cierre no disparaba ningún respaldo.
   *Causa raíz:* la detección miraba stderr, y ese fallo no escribe en stderr; y el código de salida
   era 0, indistinguible de una parada ordenada.
   *Arreglo:* el cliente marca las paradas que pide él, y un cierre que nadie ha pedido cuenta como
   fallo (ADR-042).
4. *Síntoma:* al elegir versión, el feed devuelve 763 candidatas y ninguna es estable en SemVer.
   *Arreglo:* versión fijada y verificada a mano, con descarte de las declaradas de prueba como
   camino de reserva (ADR-040). El desempate lo ganó el `runtimeconfig.json`: la banda 4.14 declara
   `net9.0` con `rollForward: Major` y arranca con el runtime 9 o el 10; las bandas 5.x exigen 10.
5. *Trampa nueva del entorno:* el argumento de `--probe=` **no puede llevar saltos de línea**. Con
   ellos el modo de diagnóstico responde `PROBE_FAIL` sin decir qué pasó, y el fallo se confunde con
   un error de la expresión. Se escriben en una sola línea.

**Verificado sobre la aplicación real** (solución `Acme.Lab` generada con el propio scaffolding,
abierta en el IDE, midiendo con `--probe=`, no mirando capturas):

- Adquisición: `[lsp] Roslyn LanguageServer 4.14.0-3.26423.7 (versión fijada por DotForge)`.
- Estado `ready`, leyenda con **82 tipos de token**, `textDocument/semanticTokens/full` devolviendo
  **1440 números**, `documentSymbol` respondiendo y completado con resultados.
- Hover real, en español y con su análisis de nulabilidad: ``(variable local) ?? builder`` y
  `"builder" no es NULL aquí`. Es la primera vez en la vida del proyecto que hay IntelliSense de C#.
- Respaldo: `acquireLanguageServer(..., { prefer: 'omnisharp' })` resuelve, instala y verifica
  **OmniSharp v1.39.15**, y contra la misma solución carga los cinco proyectos y devuelve también
  **1440 números** de tokens semánticos. La decisión de conmutar está cubierta por pruebas con el
  stderr real capturado; lo que no se ha podido montar es un Roslyn que falle **con la instalación
  íntegra**, así que ese tramo concreto está verificado por pruebas y no sobre la aplicación.
- `npm test` en verde de punta a punta: **1106 pruebas** (950 unit, 43 security, 57 package, 56
  scaffold), de las cuales 48 son nuevas de esta fase. La que estaba en rojo era del grupo de
  seguridad y tenía razón: comprobaba por grep que `acquire.ts` calculase el hash de lo descargado,
  y ese cálculo se ha mudado al instalador. Se ha reescrito para comprobar la propiedad donde ahora
  vive —y de paso la verificación de `content-length` y la de la instalación—, no para ablandarla.
  Ahora exige las tres cosas a **los dos** adquisidores, y que ninguno vuelva a declarar un `MARKER`.

- `npx electron . --smoke-test` → `SMOKE_OK`, con la línea de adquisición encima.
- Depurador: la prueba de integración descarga NetCoreDbg por el camino nuevo —su caché no tenía
  manifiesto, así que se reinstaló sola—, deja un manifiesto de **7 archivos** con el prefijo
  `netcoredbg/` descartado y `netcoredbg.exe` midiendo 2.115.072 bytes tanto en el manifiesto como
  en el disco, y con esa instalación **para en el breakpoint y lee la pila y las variables**.
- `prune:dist` liberó los 279,2 MB de artefactos de la 1.9.0 y `verify:dist` confirma el instalador
  NSIS (117,4 MB) y el ZIP portable (161,7 MB) de la 2.0.0, sin firmar como es esperado sin
  certificado.

**Versión:** el marcador de instalación cambia de formato **para todo el toolchain** —servidor de
lenguaje y depurador—, `pickLatestVersion` deja de gobernar la elección y el contrato de lo que el
cliente contesta al servidor cambia. Son cambios de comportamiento en la adquisición, y la
funcionalidad estrella del IDE pasa de no funcionar a funcionar: 1.9.0 → **2.0.0** (ADR-009).
---

### Iteración 21 — 2026-08-24 — Fase 17: actualizaciones automáticas y extensiones de Open VSX

**Objetivo:** que el IDE sepa actualizarse solo sin interrumpir a nadie, y que se puedan instalar
extensiones del registro abierto sin salir de la aplicación.

**Hecho:**

- **Actualizaciones.** Modelo puro (`src/shared/updates.ts`) con SemVer de verdad, lectura del feed
  de releases y elección del artefacto por plataforma y arquitectura; servicio
  (`updater-service.ts`) que comprueba cinco segundos después del arranque y bajo demanda, descarga
  con verificación de `content-length` y persiste lo que queda pendiente; tarjeta flotante con las
  notas de la publicación, barra de descarga y "Reiniciar y aplicar"; interruptor "Buscar
  actualizaciones automáticamente" y botón "Buscar ahora" en Ajustes.
- **Extensiones.** Cliente de Open VSX (búsqueda, categorías y ficha), instalador de `.vsix` montado
  sobre el instalador verificable del toolchain, y panel lateral con las instaladas arriba y los
  resultados del registro debajo.
- 90 pruebas nuevas: 82 unitarias y 8 de seguridad sobre las dos superficies de descarga nuevas.

**Decisiones registradas:** ADR-045 (sin `electron-updater`), ADR-046 (se aplica al cerrar, y
"Descartar" es "ahora no"), ADR-047 (host de descarga en lista blanca), ADR-048 (se instalan pero no
se ejecutan, y se dice), ADR-049 (los iconos se dibujan).

**Errores encontrados y solucionados:**

1. *Síntoma:* en Linux, la elección de artefacto se quedaba con el portable de **Windows**.
   *Causa raíz:* el filtro por extensión acepta `.zip` en las tres plataformas, y las exclusiones por
   nombre sólo estaban escritas para Windows y macOS. Un `DotForge IDE-2.2.0-win-x64.zip` pasa el
   filtro de un Linux perfectamente.
   *Arreglo:* tabla `FOREIGN_MARKERS` con las marcas de las **otras** plataformas, comprobada siempre
   y no sólo cuando la extensión es ambigua. Lo cazó la prueba antes que ningún usuario.
2. *Síntoma:* las notas de la versión salían con dos viñetas por línea.
   *Causa raíz:* `releaseNotesLines` ya convierte `- ` en `· ` —lo necesita, porque los encabezados
   no llevan marca y las viñetas sí— y encima se pintaban dentro de una `<ul>`.
   *Arreglo:* la tarjeta pinta líneas, no una lista: el modelo ya trae la marca que corresponde.
3. *Síntoma:* "Buscar ahora" contestaba `404 Not Found`.
   *Causa raíz:* el repositorio todavía no publica releases, y GitHub responde 404 a `/releases` de
   un repositorio privado o sin publicar. No es un fallo de red: es el estado normal de un producto
   que aún no ha publicado su primera versión.
   *Arreglo:* el 404 se traduce a lo que significa. El resto de códigos siguen saliendo tal cual.
4. *Trampa conocida que volvió a morder:* los índices de `--ui=` son posicionales sobre
   `.activity-item`. Añadir "Extensiones" desplazó "Ajustes" del 9 al 10 y habría roto en silencio
   `settings`, `light`, `probe-theme` y `ai-toggle`. Se actualizaron los cuatro y el comentario que
   lleva el orden escrito.

**Verificado sobre la aplicación real** (no mirando capturas: midiendo con `--probe=`):

- Búsqueda contra Open VSX de verdad: **16 920 extensiones**, con sus descargas, valoraciones y
  descripciones, pintadas en el panel.
- Instalación de un `.vsix` real de punta a punta:
  `{"id":"Shuzzy.dracula-shuzzyos","version":"1.2.1","contrib":{"supported":["temas de color"]}}`,
  descargado del registro, extraído sin el envoltorio de OPC, verificado archivo a archivo y listado
  en "Instaladas"; y desinstalado después (`removed: true`), sin dejar rastro en
  `userData/extensions/`.
- Comprobación contra el feed real: `{"status":"error","current":"2.1.0","version":null,...}` con el
  mensaje ya traducido —el repositorio no publica releases todavía—, que es la respuesta honesta y la
  que verá cualquiera que pulse "Buscar ahora" hoy.
- `--ui=update` pinta la tarjeta con un estado de ejemplo y `--ui=extensions` el panel; Ajustes sigue
  enseñando sus grupos, ahora con "Actualizaciones" entre "Lenguaje" y el asistente.
- `npx electron . --smoke-test` → `SMOKE_OK`.
- `npm test` en verde de punta a punta.
- `prune:dist` liberó los 279,2 MB de artefactos de la 2.0.0, y `verify:dist` confirma los de la
  2.1.0: instalador NSIS (117,4 MB) y ZIP portable (161,8 MB), sin firmar como es esperado sin
  certificado.

**Versión:** dos funcionalidades nuevas, compatibles hacia atrás y sin cambios de comportamiento en
lo existente: 2.0.0 → **2.1.0** (ADR-009).
---

### Iteración 22 — 2026-08-24 — Hotfix del pipeline: la suite se pone en verde en un clon limpio

**Objetivo:** que `npm test` pase en Windows y en macOS dentro de GitHub Actions. La publicación del
tag `v2.1.0` fue la primera ejecución del workflow sobre un **clon limpio**, y destapó cuatro
problemas de entorno que llevaban tiempo latentes. Ninguno venía de la Fase 17: sus 90 pruebas
pasaron en los dos runners, incluida la instalación real de un `.vsix` en disco.

Consecuencia práctica del fallo: `build-windows` y `build-macos` declaran `needs: test`, así que no
se generó ningún artefacto de la 2.1.0.

**Hecho:**

1. **CRLF (`unit`, sólo Windows).** Las plantillas se comparan con expresiones regulares que llevan
   un salto de línea dentro (la valla de código de Mermaid seguida de `flowchart`). En un clon de
   Windows, `core.autocrlf` —el valor por defecto de Git para Windows y el de los runners— entrega
   el `.tmpl` con CRLF y el patrón deja de casar. Se añade `.gitattributes` con `* text=auto eol=lf`
   y se normaliza al leer en `tests/unit/blueprints.test.mjs`, con `readTemplate()`. Las dos cosas:
   el atributo elimina la causa y la normalización hace que la prueba no dependa de la configuración
   de git de quien la ejecute.
2. **Binario de Electron (`package`, los dos runners).** `electron@43.4.1` **ya no declara script de
   instalación** —se comprobó en el paquete instalado: `scripts` es `undefined` y el descargador se
   expone como bin `install-electron`— y además npm 11 bloquea los scripts pendientes de aprobación
   (`2 packages have install scripts not yet covered by allowScripts`). El resultado es que
   `node_modules/electron/dist` no existe y la prueba de humo no tiene nada que arrancar. Se añade un
   paso explícito `node node_modules/electron/install.js` en los tres jobs, que es idempotente.
3. **Límite de la API de GitHub (`scaffold`).** `no se ha podido consultar las releases de NetCoreDbg
   (403)`. Las consultas iban sin autenticar, y ese límite es de 60 peticiones por hora **y por IP**:
   la de un runner compartido está agotada casi siempre. Se añade `src/shared/github-api.ts`, que
   decide qué cabeceras lleva cada URL y adjunta el token **sólo** a `api.github.com` (ADR-050), y se
   inyecta `GITHUB_TOKEN` en el paso `npm test`. De paso, un 403 ya no es un número suelto: dice que
   es el límite por IP y cómo salir de él.
4. **Caché de NuGet (`scaffold`, sólo macOS).** La Web API generada arrancaba y moría con
   `Could not load file or assembly 'Microsoft.EntityFrameworkCore, Version=10.0.11.0'`. El build
   tardó 7 s, que no da para una restauración fría: venía de una caché de una ejecución anterior con
   el paquete a medias —el `project.assets.json` lo daba por restaurado y el DLL no estaba—. Se sube
   la clave a `nuget-${{ runner.os }}-v2-…` y se quita `restore-keys`, porque recuperar una caché
   anterior es justamente lo que hay que evitar aquí.

**Decisión registrada:** ADR-050 — el token de GitHub sólo viaja a `api.github.com`.

**Errores encontrados y solucionados:**

1. *Síntoma:* al escribir el helper `readTemplate` por shell, el archivo quedó con saltos de línea
   **reales** dentro de la expresión regular en vez de con `\r\n`.
   *Causa raíz:* la trampa que `CLAUDE.md` ya documenta: un heredoc se come un nivel de escapes.
   *Arreglo:* reescrito con la herramienta de edición y con `new RegExp(String.raw…)`, que es la
   forma que la propia guía recomienda para no volver a pisarla. Ha vuelto a pasar; el recordatorio
   sigue siendo necesario.

**Verificado con comandos reales:**

- **El caso de Windows, reproducido y arreglado en local:** con los tres `README.md.tmpl` convertidos
  a CRLF a propósito, `node --test tests/unit/blueprints.test.mjs` pasa 49/49. Antes del cambio, el
  mismo patrón devolvía `false` sobre el texto con CRLF y `true` sobre el mismo texto normalizado.
- **El paso de Electron, ejercitado de verdad:** se apartó `node_modules/electron/dist`, se ejecutó
  `node node_modules/electron/install.js` (salida 0) y el binario volvió a estar en su sitio.
- **El alcance del token, probado:** 21 pruebas nuevas en `tests/unit/github-api.test.mjs`, entre
  ellas la lista de URLs reales del toolchain (API, CDN de artefactos, feed de Azure, Open VSX) con
  lo que debe pasar en cada una, y **una redirección real entre dos servidores locales en puertos
  distintos** que comprueba que el segundo salto no recibe `Authorization`. Más 4 pruebas
  estructurales en el grupo de seguridad: ningún adquisidor escribe cabeceras a mano y el token se
  lee en un único archivo de todo `src/`.
- `npm test` en verde de punta a punta: **1221 pruebas** (1053 unit, 55 security, 57 package,
  56 scaffold), con 25 nuevas en este hotfix.
- El YAML del workflow se valida y quedan los tres jobs con sus pasos en orden.

**Lo que este hotfix no arregla:** el workflow sube artefactos pero **no publica la release**. El tag
`v2.1.0` no creará la publicación con sus notas; eso sigue siendo manual mientras no se añada un paso
de publicación.

---

### Iteración 23 — 2026-08-24 — El test del depurador tolera un runner de CI

**Objetivo:** que la única prueba que seguía en rojo en `windows-latest` deje de serlo. Tras el
hotfix de la iteración 22 (CRLF, Electron, API de GitHub, caché de NuGet), la ejecución sobre
Windows Server 2025 falló en un solo punto, y por timeout:

```text
Error: el programa no se detuvo en el breakpoint
    at Timeout._onTimeout (tests/scaffold/debugger.test.mjs:158:35)
```

El mensaje no distingue las dos averías que puede estar tapando: que el runner sea lento, o que el
programa se muriera al arrancar y nadie llegara nunca al breakpoint. Los dos cambios de esta
iteración atacan una cada uno, y ninguno toca código de producción.

**Hecho:**

1. **Márgenes de espera más anchos sólo en CI.** `IN_CI` mira `process.env.CI`, y de ahí salen
   `BREAKPOINT_TIMEOUT_MS` (120 s → **240 s**), `RESUME_TIMEOUT_MS` (60 s → 120 s) y
   `STATUS_TIMEOUT_MS` (30 s → 60 s). Un runner virtual arranca en frío, jitea, carga los PDB
   portables y resuelve el bridge DAP sobre un disco compartido y sin caché de nada. **Fuera de CI
   se mantienen los valores originales**: en una máquina de desarrollo un timeout largo sólo
   consigue que un fallo real tarde más en verse.
2. **Volcado de la salida del proceso depurado.** `collectOutput()` se suscribe a `output` del
   controlador —que trae tanto el stdout/stderr del programa (eventos DAP) como el stderr del propio
   NetCoreDbg (evento `log`)— y adjunta las últimas 40 líneas a *todos* los mensajes de fallo:
   timeout, arranque fallido y segunda parada. Acotado a 40 para no volcar megas si el programa
   entra en un bucle escribiendo.
3. **Un final prematuro deja de esperar el timeout entero.** `waitForBreakpoint()` vigila tres
   finales en vez de uno: que pare (bien), que la sesión pase a `idle`/`error` **después** de haber
   llegado a `running` (el programa se ejecutó entero o murió), o que se agote el plazo. Los estados
   de arranque (`acquiring`, `starting`) no cuentan como final. El oyente se registra **antes** de
   `controller.start()`: el breakpoint puede golpear entre el arranque y la suscripción, y ese
   evento no se repite.

**Errores encontrados y solucionados:**

1. *Síntoma:* con el diseño anterior, un programa que termina en dos segundos sin parar y un
   programa que no responde en cuatro minutos daban **el mismo** mensaje, cuatro minutos después.
   *Causa raíz:* la espera era un `Promise.race` entre el evento `stopped` y un `setTimeout`; nadie
   miraba el estado de la sesión.
   *Arreglo:* la vigilancia del evento `state` descrita arriba. En CI esto ahorra hasta 240 s por
   ejecución cuando la avería es real, que es justo cuando interesa ver el log cuanto antes.

**Verificado con comandos reales:**

- `npm run build` en verde, y `npm test` completo: **56 pruebas de scaffold, 0 fallos**; la suite
  entera OK (unit, security, package, scaffold).
- `node --test tests/scaffold/debugger.test.mjs` pasa 3/3 y para en el breakpoint en **1,4 s** en
  local: los 240 s de CI son margen, no una espera que se vaya a consumir.
- La misma prueba con `CI=1`, para ejercitar la rama de los márgenes anchos: 3/3.
- **El volcado, ejercitado de verdad:** con una copia de la prueba apuntando el breakpoint a una
  línea inexistente (999), el fallo llega en **1,0 s** en vez de a los 240 s, y con el diagnóstico
  dentro: `la sesión terminó antes de llegar al breakpoint (estado "idle")` seguido de los tres
  eventos de stdout del programa (`1`, `3`, `6`, `total=6`). Es exactamente la traza que faltaba en
  el fallo de Windows Server 2025.

---

### Iteración 24 — 2026-08-24 — No era el timeout: dos bugs reales del depurador

**Objetivo:** arreglar el fallo del depurador en CI. La iteración 23 lo trató como lentitud del
runner y amplió los márgenes de espera. **Era un diagnóstico equivocado**, y lo demostró el volcado
de diagnóstico que se añadió en esa misma iteración: en cuanto el fallo trajo la salida del proceso,
se vio que el programa se ejecutaba **entero** —`1`, `3`, `6`, `total=6`— y terminaba en 1,5 s. No se
estaba agotando ningún plazo: el breakpoint no se ligaba nunca. Ampliar el timeout sólo habría hecho
que el mismo fallo tardara más en aparecer.

Detrás había dos averías distintas, una por plataforma, y las dos son de **código de producción**, no
de la prueba. La prueba era lo único que las estaba destapando.

**Hecho:**

1. **Windows — el alias 8.3 dejaba el breakpoint sin ligar.** NetCoreDbg resuelve un breakpoint
   comparando **como texto** la ruta pedida con la que guarda el PDB. En los runners de Windows el
   usuario es `runneradmin`, que no cabe en 8.3, así que `%TEMP%` llega como
   `C:\Users\RUNNER~1\AppData\Local\Temp` y `os.tmpdir()` lo devuelve tal cual. El compilador guarda
   siempre la forma larga ⇒ las dos cadenas no casan, el breakpoint se queda pendiente para siempre
   y **no hay ningún error**. Ahora `DebugSession.setBreakpoints` canonicaliza la ruta con
   `debuggerSourcePath()` justo en la frontera con el adaptador, para que ningún camino nuevo se
   olvide. Le pasaba igual a cualquier usuario con el proyecto bajo una ruta con `~1`
   (`C:\PROGRA~1\…`, `%TEMP%`, un acceso directo antiguo).
2. **macOS — el depurador no se ha podido instalar en ninguna versión publicada.** El ZIP de
   NetCoreDbg para macOS se comprime en un Mac y trae el árbol `__MACOSX/` de bifurcaciones de
   recurso. Con `strip: 1`, `__MACOSX/netcoredbg/._Microsoft.CodeAnalysis.dll` se queda en
   `netcoredbg/._…` y **crea una carpeta llamada igual que el ejecutable**; como esa entrada va antes
   en el directorio central, al escribir el binario el nombre ya está ocupado y muere con `EISDIR`.
   `extractTo` descarta ahora `__MACOSX/`, los `._*` y `.DS_Store`, antes que el filtro de quien
   llama: no es una preferencia del paquete, es basura del empaquetado. Vale para todo lo que se
   extrae, incluidos los `.vsix` de Open VSX, que también se publican comprimidos desde un Mac.

**Errores encontrados y solucionados:**

1. *Síntoma:* el fallo de `windows-latest` parecía un timeout, y se arregló como un timeout.
   *Causa raíz:* el mensaje no distinguía "no ha dado tiempo" de "no va a parar nunca". Sin la
   salida del proceso, las dos averías se ven igual.
   *Arreglo:* el de esta iteración. La lección se queda: **el primer arreglo de la 23 sobraba y el
   segundo era el que valía.** Los márgenes anchos en CI se conservan porque no estorban, pero no
   son los que ponen esto en verde.
2. *Síntoma:* `realpath` no expandía el alias 8.3 y la primera versión del arreglo no cambiaba nada.
   *Causa raíz:* el `realpath` de JavaScript resuelve enlaces simbólicos pero devuelve `DOTFOR~1`
   tal cual; sólo el **nativo** llama al sistema y da el nombre largo. Además `fs/promises` no
   expone `realpath.native`: hay que promisificar el de `node:fs`.
   *Arreglo:* medido antes de escribir el arreglo, no supuesto, y anotado en el propio código.

**Verificado con comandos reales:**

- **El caso de Windows, reproducido y luego arreglado**, con A/B en la misma máquina y el mismo
  NetCoreDbg: compilando y depurando bajo un alias 8.3 el programa corría entero y escribía
  `1 3 6 total=6` —los mismos bytes que el log de CI—; en forma larga paraba. Tras el arreglo, la
  misma reproducción responde `verified: true` y para en la línea 5.
- **Un tercer experimento decidió hacia dónde normalizar:** compilando bajo la ruta corta y pidiendo
  el breakpoint con la larga, liga. O sea, el PDB guarda la larga y hay que expandir, no acortar.
- **El caso de macOS, con el paquete de verdad**, no con una maqueta: descargado
  `netcoredbg-osx-arm64.zip` de la release 3.2.0-1092 e instalado con `installArchive`. Sin el
  arreglo, `EISDIR ... open .../netcoredbg`, idéntico al de CI; con él, `netcoredbg` queda como
  archivo de 2.625.896 bytes y `verifyInstall` da verde sin problemas.
- **Las pruebas nuevas se comprobaron en rojo antes que en verde:** con el arreglo de `zip.ts`
  apartado, las dos de macOS fallan; con él, pasan. Una prueba que no puede fallar no prueba nada.
- `npm run build`, `npx tsc --noEmit` y `npm test` en verde: **1226 pruebas** (1058 unit, 55
  security, 57 package, 56 scaffold), 5 nuevas.

**Lo que esta iteración NO arregla:** el fallo de `runtime-smoke` en macOS
(`Could not load file or assembly 'Microsoft.EntityFrameworkCore, Version=10.0.11.0'`). Sigue
abierto y **no** es lo que se creyó en la iteración 22: esta vez la caché de NuGet ni siquiera se
restauró (`Cache not found`) y volvió a fallar, así que la explicación de "caché a medias" no se
sostiene. La pista que queda es que `node --test` ejecuta los archivos en paralelo y varios
`dotnet build` restauran a la vez sobre un `~/.nuget/packages` frío. No se ha tocado porque no se
puede reproducir ni verificar desde Windows, y un arreglo a ciegas en el pipeline es justo lo que ha
costado esta iteración.

---

### Iteración 25 — 2026-08-24 — Ajuste de aserción 8.3 en Windows y skip de runtime-smoke en CI de macOS

**Objetivo:** desbloquear el pipeline sin tener un Mac delante. La ejecución del tag sobre `cb0f842`
volvió en rojo en las dos plataformas, pero por motivos distintos y de gravedad muy distinta: en
Windows fallaba **la prueba nueva, no el arreglo**; en macOS seguía el fallo de EF Core sin
diagnosticar.

**Hecho:**

1. **Windows — la aserción de `tests/unit/debug-source-path.test.mjs` estaba mal, y del mismo modo
   que el bug que arregla.** La prueba comparaba la ruta expandida contra `join(tmpdir(), …)`, o sea
   contra una referencia que daba por "larga" sin canonicalizarla. En esta máquina `%TEMP%` no tiene
   ningún componente 8.3 y pasaba; en el runner **sí lo tiene** (`RUNNER~1`), así que la referencia
   tampoco era larga y la prueba se caía enseñando la expansión correcta en `actual` y el alias en
   `expected`. Ironía completa: el código estaba bien y la prueba cometía el error que el código
   evita. Ahora no se compara contra una cadena concreta —el nombre de usuario cambia en cada
   máquina y no se puede fijar `runneradmin`— sino contra la invariante que de verdad necesita
   NetCoreDbg: que **las dos formas de escribir la ruta converjan a la misma**, que no quede ningún
   `~N`, y que el resultado apunte al archivo de verdad (se comprueba leyendo su contenido).
2. **macOS — `runtime-smoke` congelada, y sólo en CI.** Guarda `process.platform === 'darwin' &&
   Boolean(process.env.CI)`, con motivo *"Congelado temporalmente hasta verificación en hardware
   macOS real"*. Es deliberadamente estrecha: en un Mac de desarrollo la prueba **sigue corriendo**,
   que es justo donde habrá que diagnosticar el fallo; en Windows y en local no cambia nada.
3. **macOS desactivado en el workflow, sin borrarlo.** La pata `macos-latest` de la matriz y el job
   `build-macos` quedan comentados bajo la marca `MACOS-DESACTIVADO`, con las instrucciones de
   reactivación en la cabecera de `release.yml`. Se comenta en vez de borrarse para que volver sea
   descomentar y no reinventar la receta. **Lo que se paga:** mientras esté así no se generan
   `.dmg` ni `.app`, porque ese runner es la única vía —electron-builder desde Windows los empaqueta
   pero no puede firmarlos—. Los dos puntos anteriores son complementarios, no redundantes: hoy la
   guarda no se dispara nunca porque macOS ni corre, y existe para que **reactivar macOS no vuelva a
   tropezar de inmediato** con el fallo de EF Core.

**Errores encontrados y solucionados:**

1. *Síntoma:* la prueba `flujo de macOS` de `tests/package/packaging.test.mjs` habría seguido en
   verde después de comentar el job, afirmando que el workflow construye macOS.
   *Causa raíz:* sus aserciones eran `/runs-on:\s*macos-latest/` contra el archivo entero, y esa
   expresión casa igual de bien con la línea comentada.
   *Arreglo:* se separan las líneas activas de las comentadas antes de mirar nada. Ahora hay tres
   pruebas: que ninguna línea **activa** menciona macOS, que la receta **comentada** sigue completa
   (para poder reactivarla), y que Windows conserva su camino de artefactos.
2. *Síntoma:* al reescribir esa prueba por shell, el archivo quedó con saltos de línea reales dentro
   de un `split('\n')` y dejó de parsear.
   *Causa raíz:* la trampa que `CLAUDE.md` ya documenta —un heredoc se come un nivel de escapes—,
   esta vez a través de `python - <<'PYEOF'`.
   *Arreglo:* restaurado y reescrito con la herramienta de edición. Van cuatro veces; la regla no es
   una recomendación.

**Verificado con comandos reales:**

- **El fallo de Windows, reproducido en local antes de tocarlo:** con `%TEMP%` apuntando a un alias
  8.3 y `CI=1`, la prueba falla con exactamente el mismo par `actual`/`expected` que el runner
  (`...\DO3E53~1\...` frente a la forma expandida). Tras el arreglo, 3/3 bajo esa misma condición.
- **La guarda del skip, comprobada en sus cuatro casos** sin depender de la plataforma real: omite en
  macOS+CI y ejecuta en Mac de desarrollo, Windows+CI y Windows local.
- **El YAML del workflow se parsea** tras comentar el job: quedan los disparadores `push` y
  `workflow_dispatch`, los jobs `test` y `build-windows`, y la matriz en `["windows-latest"]`.
- `npm test` en verde de punta a punta.

**Lo que sigue abierto:** el fallo de EF Core en macOS. Lo que se sabe, y conviene no volver a
perder: la aplicación **compila y arranca**, y muere al resolver la dependencia con
`FileNotFoundException` —no `BadImageFormatException`—, así que el DLL no estaba en el directorio de
salida y la compilación lo dio por bueno igualmente. Además, `runtime-smoke` lanza `dotnet run` con
`stdio: ['ignore', 'pipe', 'pipe']` y **sólo consume `stderr`**: toda la salida de restore y build se
descarta, que es la parte que explicaría por qué no se copió. Antes de proponer ninguna hipótesis en
un Mac, capturar esa salida.

### Iteración 26 — 2026-08-24 — Fase 18: tres bugs de uso y dos mejoras de UX

**Objetivo:** tres fallos que se notan usando el IDE y no aparecen en ningún registro —el editor que
deja de admitir texto, el cursor que se pierde al buscar, la ventana que se congela instalando— y dos
huecos de UX: instalar un paquete en varios proyectos a la vez y poder ordenar la barra de actividad.

**Hecho:**

- **Instalar deja de bloquear el hilo principal** (ADR-051). `readEntryAsync` con `inflateRaw` (pool
  de libuv) y `sha256Async` troceado en bloques de 4 MiB; fuera `existsSync` de los dos instaladores.
- **El repintado devuelve el foco** (ADR-052). `data-focus-key` + `repaintPreservingFocus`, con las
  reglas en un módulo puro. De paso, las respuestas de búsqueda que llegan tarde ya no pisan a las
  nuevas, y la casilla "pre" de NuGet se pinta desde el estado en vez de reconstruirse en blanco.
- **El editor recalcula si se puede escribir** (ADR-053), en cada punto de control y en el `finally`
  de toda operación asíncrona. Y `save()` deja de tragarse sus fallos.
- **NuGet instala en varios proyectos a la vez**: casillas por proyecto, "Todos"/"Ninguno", barra de
  progreso global e instalación en serie con resumen que nombra los proyectos que fallan.
- **La barra de actividad se reordena arrastrando** (ADR-054), con el orden en `activityBar.order` y
  los `--ui=` pulsando por `data-tool-id`.
- 79 pruebas nuevas: 72 unitarias (barra de actividad 19, instalación en varios proyectos 18, foco 15,
  estado del editor 12, responsividad de la instalación 8) y 7 estructurales de endurecimiento.

**Decisiones registradas:** ADR-051 (nada de CPU síncrona en el proceso principal), ADR-052 (el
repintado devuelve el foco), ADR-053 (el estado de escritura se recalcula), ADR-054 (barra ordenable
y pulsada por identificador).

**Errores encontrados y solucionados:**

1. *Síntoma:* el editor admitía borrar y no admitía escribir.
   *Causa raíz:* **no se encontró ningún camino que encienda `readOnly`** en el editor de código —lo
   declara sólo el editor de diferencias, y ahí es por diseño (ADR-021)—. Lo que sí es cierto, y es
   lo que hace posible el fallo, es que el valor era una suposición que nadie revisaba nunca:
   `readOnly` en Monaco es pegajoso y no se apaga solo.
   *Arreglo:* una regla única y pura, recalculada en cada punto de control. No se ha "arreglado al
   culpable" porque hoy no existe; se ha quitado la propiedad que lo haría posible mañana. Queda
   escrito para que la próxima sesión no vuelva a buscarlo a ciegas.
2. *Síntoma:* la primera versión de las pruebas de responsividad daba un verde falso, con el
   **control** en rojo.
   *Causa raíz:* medían el hueco más largo entre disparos de un temporizador y exigían que fuera
   corto. Esta máquina hashea 96 MB en 17 ms —SHA-NI—, así que ni siquiera el camino síncrono
   llegaba al umbral. Una prueba calibrada contra la CPU de quien la escribe no vale para la máquina
   de al lado.
   *Arreglo:* se mide cuántas vueltas da el bucle de eventos, que es invariante: cero en el camino
   síncrono, una por bloque o por archivo en el asíncrono. Cada medición conserva su control.
3. *Síntoma:* la instalación en varios proyectos moría después del segundo, sin decir nada.
   *Causa raíz:* instalar cambia el `.csproj`, así que el renderer relee la solución al terminar
   **cada** tarea de `dotnet`; `setSolution` trataba toda relectura como "otra solución" y reiniciaba
   su estado, tirando la selección del usuario y el plan en marcha.
   *Arreglo:* sólo se reinicia cuando la solución cambia de verdad (ruta y directorio). En una
   relectura sólo se descartan los proyectos que hayan desaparecido del `.sln`.
4. *Síntoma:* soltar un icono de la barra no movía nada a la vista, aunque la preferencia sí se
   guardaba.
   *Causa raíz:* dos cosas a la vez. `applySettings` sólo repinta la barra cuando el parche toca al
   asistente; y la guarda que debía evitar guardar por nada (`order === this.activityOrder()`)
   comparaba contra otra llamada que normaliza y devuelve **un array nuevo**, así que nunca era
   cierta.
   *Arreglo:* repintar cuando el parche trae `activityBar`, y comparar contra el array que se le pasó
   a `moveActivityTool`.
5. *Síntoma:* la suite se quedaba colgada indefinidamente tras un timeout de la prueba de humo.
   *Causa raíz:* `child.kill()` en Windows mata sólo al padre; los procesos de GPU y renderer de
   Electron siguen vivos con la tubería de salida abierta y `node --test` no puede salir.
   *Arreglo:* `taskkill /T` y las tuberías sueltas.
6. *Trampa conocida que volvió a morder:* un heredoc se come un nivel de escapes. Pasó dos veces al
   escribir por shell archivos con literales de plantilla dentro. Van seis. Reescritos con la
   herramienta de edición, que es lo que la propia guía dice desde la Iteración 22.

**Verificado sobre la aplicación real** (con `--probe=`, no mirando capturas):

- **El foco, con la búsqueda de verdad contra nuget.org:** se escribe "Serilog", se deja el cursor en
  la posición 3, se espera a que salte el rebote y lleguen los 30 resultados —dos repintados
  completos— y la respuesta es
  `enfocado=nuget-search valor=Serilog cursor=3 resultados=30`.
- **La instalación en varios proyectos, de punta a punta** sobre una solución Clean generada con el
  wizard: `6 proyectos seleccionados`, el botón dice `Instalar en 6` y su tooltip nombra los seis; el
  progreso avanza (`Humanizer.Core 3.0.10: 2 de 6 — Acme.Shop.Application`, `3 de 6 —
  Acme.Shop.Infrastructure`, `4 de 6 — Acme.Shop.Blazor`) y al final los **seis** `.csproj` tienen su
  `<PackageReference Include="Humanizer.Core" />` con la versión centralizada en
  `Directory.Packages.props`, que es lo que hace el SDK en una solución con gestión centralizada.
- **La barra de actividad:** los once botones salen con su `data-tool-id` y "Ajustes" no es
  arrastrable; un arrastre de "Extensiones" al primer puesto deja DOM y preferencias de acuerdo
  (`dom=extensions explorer git … settings`, `settings=extensions explorer git …`), sobrevive a un
  reinicio, y `--ui=nuget` sigue abriendo NuGet con la barra reordenada — que es exactamente lo que
  los índices posicionales no habrían soportado.
- **La instalación, medida en el proceso principal y no en la teoría:** durante la instalación real
  de dos extensiones de Open VSX se le pide al proceso principal una respuesta cada 30 ms y se
  cronometra la peor. `Telokis.theme-dracula-at-dusk` (874 ms de instalación, 15 muestras) y
  `devshub-ai.devshub-file-icons` (3,8 s, 120 muestras): **peor respuesta 2 ms** en los dos casos.
  El proceso principal no deja de atender en ningún momento.
- **Lo que no se ha conseguido reproducir, y conviene decirlo:** con el camino síncrono restaurado a
  propósito, esas dos mismas instalaciones dan también 1-2 ms de peor respuesta. Un `.vsix` corriente
  son muchos archivos pequeños, y entre archivo y archivo ya había un `await writeFile` que cedía el
  bucle. El bloqueo largo aparece con **archivos grandes**, que es el caso del toolchain: medido
  sobre el `Microsoft.CodeAnalysis.CSharp.dll` real de Roslyn (18,3 MB), `inflateRawSync` de ese solo
  archivo son **50 ms** de hilo principal parado, y el `sha256` del paquete entero otros **51 ms**
  por cada 96 MB — en esta máquina, que tiene SHA-NI; en una sin él, varias veces más. Son tirones
  de tres o cuatro fotogramas cada uno, repetidos por cada archivo grande del paquete. El arreglo es
  correcto y está probado, pero **el síntoma severo no se ha reproducido en este hardware**, y quien
  lo retome debería medirlo en la máquina donde se ve.
- `npx electron . --smoke-test` → `SMOKE_OK`.
- `npm test` en verde de punta a punta: **1192 pruebas** entre `unit` y `security` (1113 antes), más
  los grupos `package` y `scaffold`.

**Versión:** dos funcionalidades nuevas y tres correcciones, sin cambios incompatibles:
2.1.0 → **2.2.0** (ADR-009).

**Lo que queda anotado para la próxima sesión:** el fallo del editor no tiene hoy un culpable en el
código. Si vuelve a aparecer, lo primero es mirar `readOnlyMessage` — ahora Monaco dice por qué no
deja escribir— y `editorContext()`, en vez de volver a buscar quién enciende `readOnly`.

---

### Iteración 27 — 2026-08-24 — Fase 19 (1/2): la terminal navega por el disco

**Objetivo:** poder cambiar de directorio en la terminal integrada —ir a otra solución, a otra
unidad, a la carpeta de al lado— con el prompt diciendo dónde estás, como en cualquier terminal.

**Hecho, archivo a archivo:**

- `src/shared/terminal-cwd.ts` (**nuevo**): modelo puro. `classifyLine` decide qué pretende una
  línea ya troceada —`cd`, `chdir`, `Set-Location`, `sl`, el `cd /d` de cmd, `D:` a secas,
  `pwd`/`Get-Location`/`gl`— y `resolveTarget` traduce los atajos (`~`, `~/algo`, `-`, unidad
  suelta, `cd` a secas). `shortenPath` decide cómo se enseña la ruta y `elide` la recorta por el
  medio cuando no cabe.
- `src/main/services/terminal-session.ts` (**nuevo**): la mitad que necesita disco. Resuelve con
  `node:path`, comprueba con `stat` que el destino existe y es un directorio, y recuerda el anterior
  para `cd -`. No importa `electron`.
- `src/main/ipc/register.ts`: `terminal:run` clasifica **antes** de lanzar nada y devuelve
  `TerminalRunResult`; nuevo canal `terminal:cwd`; `syncTerminalContext()` en los tres momentos que
  lo necesitan (registrar, abrir workspace, cerrar workspace) **y en `openWorkspaceFromCli`**, que
  es donde estaba el bug latente.
- `src/shared/contracts.ts`: `TerminalCwd`, `TerminalRunResult`, canal `terminal:cwd`, y la firma de
  `terminal.run` deja de devolver una tarea a secas.
- `src/main/preload.ts`: `terminal.cwd()` y el nuevo tipo de retorno de `terminal.run`.
- `src/renderer/views/panel.ts`: la ruta delante del `❯` con la completa en el `title`;
  `setTerminalCwd` y `appendTerminalLine`; `paintPrompt` repinta **sólo el span** de la ruta; y
  `render()` pasa a envolverse en `repaintPreservingFocus`.
- `src/renderer/index.ts`: `runTerminalCommand` deja de exigir carpeta abierta, pinta lo que la línea
  devuelva y sólo engancha canal si hubo tarea; el `cwd` se pide en su propio `try`.
- `src/renderer/styles/components.css`: `.terminal-cwd`, en `--text-muted` y con `max-width`.
- `tests/unit/terminal-cwd.test.mjs` y `tests/unit/terminal-session.test.mjs` (**nuevos**),
  `tests/security/hardening.test.mjs` (2 aserciones estructurales).

**Decisión registrada:** ADR-055 — la frontera de la terminal es qué se ejecuta, no desde dónde.

**Errores encontrados y solucionados:**

1. *Síntoma:* arrancar con `--open=` dejaba la terminal en la carpeta personal mientras el
   explorador enseñaba la solución. Dos verdades a la vez.
   *Causa raíz:* `openWorkspaceFromCli` **duplica** parte de `openWorkspaceDirectory` —no avisa al
   renderer ni arranca el LSP, porque no hay renderer todavía— y por eso se saltó también la
   sincronización nueva. Es duplicación preexistente que este cambio ha puesto a la vista.
   *Arreglo:* `syncTerminalContext()` también ahí. Queda anotado que ese camino hay que tocarlo cada
   vez que se añada estado ligado al workspace.
2. *Síntoma:* al lanzar un comando se perdía el foco de la terminal y el texto a medias.
   *Causa raíz:* `taskStarted` y `taskFinished` llaman a `render()`, que reconstruye el panel entero
   —y con él el `<input>`—. Es exactamente el fallo de los paneles de búsqueda (ADR-052), en un sitio
   donde nadie lo había buscado porque el disparador no es teclear sino que **termine una tarea**:
   cualquier compilación de fondo que acabara mientras se escribía se llevaba la línea por delante.
   *Arreglo:* `data-focus-key` en el input y `repaintPreservingFocus` alrededor de `render()`. Viaja
   en este commit aunque sea de otra familia: sin él, el arreglo del `cd` se notaría a medias.
3. *Síntoma:* la primera versión de la prueba de `cd -` fallaba.
   *Causa raíz:* la prueba, no el código: hacía `cd src` y luego `cd tests` esperando que `tests`
   colgara de la raíz. Colgaba de la raíz, no de `src`.
   *Arreglo:* `cd ../tests`. Anotado porque es la clase de error que, si se "arregla" en el código en
   vez de en la prueba, rompe la resolución relativa para todos.

**Verificado sobre la aplicación real** (con `--probe=`, sobre una solución Clean generada con el
asistente):

- La secuencia completa, con el prompt contestando en cada paso:
  `prompt-inicial=Acme.Shop`, `cd src → Acme.Shop\src`, `pwd → C:\…\Acme.Shop\src`,
  `cd .. → Acme.Shop`, `cd - → Acme.Shop\src`, `cd → Acme.Shop`, `cd ~ → ~`.
- **Un destino inválido dice la ruta resuelta:** `cd no-existe → no existe la carpeta
  C:\…\scratchpad\demo\Acme.Shop\no-existe`, y la sesión se queda donde estaba.
- **Los comandos se ejecutan de verdad en el nuevo directorio:** escribiendo en la caja como un
  usuario, `cd src/Acme.Shop.Domain` deja el prompt en `Acme.Shop\src\Acme.Shop.Domain` (con la ruta
  completa en el `title`) y `dotnet --version` contesta `10.0.400` desde ahí.
- **El foco sobrevive:** con `git st` a medias y el cursor en la posición 4, lanzar otra línea deja
  `enfocado=terminal-input, valor=git st, cursor=4`.
- `npx electron . --smoke-test` → `SMOKE_OK`; `unit` + `security` en verde con **1248 pruebas**
  (1192 antes).

---

### Iteración 28 — 2026-08-24 — Fase 19 (2/2): la barra de menú enseña el IDE entero

**Objetivo:** una barra de menú superior tradicional que sirva para llegar a todo, para quien
prefiere menús a la paleta de comandos.

**Hecho, archivo a archivo:**

- `src/shared/menu-template.ts` (**nuevo**): la barra entera como dato puro — diez secciones más el
  menú de aplicación de macOS —, `ROLE_ACCELERATORS` (lo que Electron le pone a cada `role` por su
  cuenta), `acceleratorOf`, `normalizeAccelerator` y `acceleratorClashes`.
- `src/main/menu.ts`: se queda sólo con la traducción a Electron, el submenú de recientes y los
  enlaces externos. Recibe sus dos dependencias inyectadas en vez de importarlas.
- `src/main/main.ts`: le inyecta los ganchos al menú y añade `--menu-dump`.
- `src/main/ipc/register.ts`: `listRecentWorkspaces`, `openRecentFromMenu`, el diálogo
  `workspace:open-solution-dialog` y la reinstalación del menú al abrir solución.
- `src/shared/contracts.ts`: catorce ids nuevos en `MenuCommand` y el canal del diálogo.
- `src/main/preload.ts`: `workspace.openSolutionDialog()`.
- `src/renderer/index.ts`: siete comandos nuevos de paleta y los métodos `openSolutionDialog`,
  `closeWorkspace` y `openSolutionDocs`.
- `src/renderer/views/explorer.ts`: `focusFilter()` extraído y el arreglo del filtro (ver abajo).
- `src/main/testable.ts`, `tests/unit/menu-template.test.mjs` (**nuevo**).

**Decisión registrada:** ADR-056 — el contenido del menú es un dato puro.

**Errores encontrados y solucionados:**

1. *Síntoma:* tres aceleradores duplicados que ninguna prueba veía.
   *Causa raíz:* **los `role` de Electron traen acelerador aunque no lo declaren.**
   `togglefullscreen` se quedaba `F11` —que en un IDE es "paso a paso por instrucciones"— y `close`
   se quedaba `Ctrl+W`, que es "cerrar pestaña". La comprobación de choques miraba sólo los
   aceleradores escritos, o sea la mitad de las teclas, y daba verde.
   *Arreglo:* `ROLE_ACCELERATORS`, la comprobación mirando también los heredados, y el criterio de
   desempate escrito: donde chocan Electron y Visual Studio, gana Visual Studio. Los dos primeros
   choques los encontró `--menu-dump` sobre el menú ya construido; el tercero —el mismo `Ctrl+W` en
   el Archivo de macOS— ya lo encontró la prueba reforzada, que es exactamente para lo que se
   reforzó.
2. *Síntoma:* la prueba afirmaba que el renderer no conoce **ningún** comando del menú.
   *Causa raíz:* la trampa que `CLAUDE.md` documenta desde la Iteración 22, dos veces seguidas en la
   misma línea: escribir `\b` por shell deja un **carácter de retroceso literal** (0x08) en el
   archivo. El patrón deja de casar, no se ve al leerlo, y el fallo parece del código.
   *Arreglo:* `new RegExp(String.raw…)` escrito con la herramienta de edición, más un comentario en
   la propia línea. Van ocho veces.
3. *Síntoma:* "Buscar archivos por nombre" abría el explorador y no pasaba nada más.
   *Causa raíz:* **bug preexistente desde la Fase 7.** `focusFilter` abre la caja poniendo un
   espacio como centinela de "abierta y vacía", y el render la pintaba sólo si
   `this.filter.trim() !== ''`. Un espacio recortado es vacío, así que el botón "Filtrar por
   nombre" de la barra de la vista llevaba desde entonces sin hacer nada visible.
   *Arreglo:* abrir la caja mira el valor sin recortar; filtrar de verdad sigue mirando el
   recortado, porque un espacio no puede descartar archivos.

**Lo que no se ha hecho, y por qué:** el enunciado pedía "buscar en archivos" en el menú Editar.
DotForge **no busca dentro del contenido** de los archivos —no hay ni servicio ni índice— y añadir
esa búsqueda es una funcionalidad, no una entrada de menú. La entrada existe, se llama **"Buscar
archivos por nombre…"** y filtra el árbol del explorador, que es lo que de verdad hace. Prometer una
búsqueda de contenido y filtrar por nombre sería peor que no ofrecerla.

**Verificado sobre la aplicación real:**

- `--menu-dump` construye las **10 secciones** sin que Electron rechace ningún `role` ni ningún
  acelerador, y `MENU_OK`. Pasado por `sort | uniq -d` sobre los aceleradores impresos: **ninguno
  repetido**.
- El submenú de recientes se llena de verdad: `Soluciones recientes (8)`.
- Los comandos nuevos, ejercitados desde la paleta como los usaría una persona: `Tema claro` dos
  veces seguidas deja el tema en `dotforge-light` —no es un conmutador disfrazado— y `Tema oscuro`
  lo devuelve a `dotforge-dark`; `Cliente HTTP` deja activa la pestaña `HTTP`; `Documentación de la
  solución abierta` abre `README.md` en el editor; `Cerrar la solución` deja
  `workspace.current() === null` y devuelve la terminal a `~`.
- El filtro del explorador, tras el arreglo: la barra aparece, recibe el foco y filtra.
- `npx electron . --smoke-test` → `SMOKE_OK`; `unit` + `security` en verde con **1269 pruebas**
  (1248 tras el módulo de la terminal, 1192 antes de la fase).

---

### Iteración 29 — 2026-08-24 — Fase 20: buscar dentro de los archivos

**Objetivo:** cerrar el agujero que la Iteración 28 dejó documentado. El menú tenía "Buscar archivos
por nombre…" porque DotForge **no sabía buscar dentro del contenido**: ni servicio, ni panel, ni
canal. Filtrar el árbol por nombre es otra cosa, y llamarla "buscar en archivos" habría sido peor
que no ofrecerla.

**Hecho, archivo a archivo:**

- `src/shared/file-search.ts` (**nuevo**): el modelo. `buildSearchRegExp` (texto plano, mayúsculas,
  palabra completa, expresión regular), `matchesInLine`, `previewOf`, `searchContent`,
  `globToRegExp` / `compileGlobs` / `matchesGlobs`, `looksBinary`, `hasBinaryExtension`,
  `coerceSearchOptions` y `describeResults`. Sin disco y sin DOM.
- `src/main/services/search-service.ts` (**nuevo**): el recorrido. Generador asíncrono con ocho
  lectores tirando del mismo iterador, lotes emitidos mientras se busca, y un contador de generación
  que hace de identificador de búsqueda **y** de testigo de cancelación.
- `src/shared/contracts.ts`, `src/main/preload.ts`, `src/main/ipc/register.ts`: `search:in-files`,
  `search:cancel` y `event:search-progress`. La raíz sale de `getWorkspaceRoot()`; cerrar la
  solución cancela lo que hubiera en marcha.
- `src/renderer/views/search.ts` (**nuevo**): el panel. Rebote de 300 ms, foco conservado, banderas,
  filtros plegables, grupos por archivo y la coincidencia resaltada dentro de la línea.
- `src/renderer/views/editor.ts`: `open()` acepta `length` y **selecciona** lo encontrado.
- `src/shared/activity-bar.ts`: `search` como herramienta reordenable.
- `src/shared/menu-template.ts` y `src/renderer/index.ts`: `search.findInFiles` con `Ctrl+Shift+F`;
  el filtro por nombre del explorador se queda con `Ctrl+P`.
- `src/main/main.ts`: `--ui=search`.
- `src/renderer/styles/components.css`, `src/main/testable.ts`, `tests/unit/file-search.test.mjs`
  (**nuevo**), `tests/unit/search-service.test.mjs` (**nuevo**), `tests/security/hardening.test.mjs`,
  `tests/unit/menu-template.test.mjs`, `tests/unit/activity-bar.test.mjs`.

**Decisión registrada:** ADR-057 — la raíz de la búsqueda la pone el proceso principal.

**Errores encontrados y solucionados:**

1. *Síntoma:* `TS1109: Expression expected` en la línea 10 de un archivo recién escrito, y otros
   veinte errores detrás que no tenían ningún sentido.
   *Causa raíz:* la cabecera del archivo ponía `src/**/*.razor` como ejemplo de glob. Eso mete un
   `*/` en mitad de un comentario de bloque: **el comentario termina ahí** y el resto del párrafo
   pasa a ser código. Ningún error menciona el comentario.
   *Arreglo:* el ejemplo escrito partido. Anotado en `CLAUDE.md`.
2. *Síntoma:* buscar `*.{cs,razor}` en la caja de inclusión no encontraba nada.
   *Causa raíz:* la coma hace dos cosas —separa patrones de la lista y separa alternativas dentro de
   `{}`—, y trocear por comas a secas dejaba `*.{cs` y `razor}`, dos patrones inservibles que no
   casan con nada y no explican por qué.
   *Arreglo:* el troceo lleva la cuenta de las llaves abiertas. Lo cazó una prueba escrita antes de
   mirar el código, que es exactamente para lo que estaba.
3. *Síntoma:* la medición del foco decía que el cursor acababa en 8 y no en 4, o sea que el arreglo
   de la Fase 18 no funcionaba en este panel.
   *Causa raíz:* **la medición**. El probe guardaba el `<input>` en una variable, y el repintado ya
   lo había sustituido: se estaba midiendo un nodo desconectado, con su valor viejo y su cursor
   viejo, mientras el vivo estaba en otra parte.
   *Arreglo:* volver a consultar el selector en cada paso y comprobar contra `document.activeElement`.
   Repetida, la medición da 4 con el nodo ya sustituido, que es justo lo que se quería demostrar.
4. *Síntoma:* `--probe=` contestaba `PROBE_FAIL` sin más detalle con una expresión que se leía bien.
   *Causa raíz:* empezaba por `const`. La expresión va envuelta en `Promise.resolve(...)`, así que
   admite una expresión, no sentencias. La trampa documentada decía "en una sola línea"; le faltaba
   la mitad.
   *Arreglo:* devolver una `Promise` y hacer dentro lo que haga falta. Anotado en `CLAUDE.md`.
5. *Síntoma:* dos viñetas de `CLAUDE.md` quedaron con las comillas vacías donde debía poner `\b`.
   *Causa raíz:* la trampa de siempre, la décima vez: **escribir contrabarras a través del shell**.
   El heredoc se comió un nivel y `\b` acabó siendo un retroceso literal (0x08) dentro del
   documento, invisible al leerlo.
   *Arreglo:* reparado y reescrito con la herramienta de edición. La ironía de que le pasara a la
   viñeta que explica por qué `\b` no sirve para "palabra completa" queda anotada aquí.

**Lo que no se ha hecho, y por qué:** no hay **reemplazo** en todos los archivos. Buscar es leer y
reemplazar es escribir en decenas de archivos de golpe, con vista previa por archivo, deshacer y
qué hacer con los que están abiertos y sucios. Es una funcionalidad entera, no el botón de al lado,
y a medias sería peligrosa. Tampoco se busca fuera de la solución abierta (ADR-057): el camino para
eso es abrir esa carpeta.

**Verificado sobre la aplicación real**, con una solución Clean generada:

- **294 resultados en 23 archivos en 20 ms** buscando `Product`; con "palabra completa", 112 en 15
  archivos. Con `*.cs, !*Tests*` en la caja de inclusión, 133 y ningún archivo de pruebas.
- **El salto es exacto:** pulsar `src/Acme.Shop.Application/DependencyInjection.cs:4:29` abre la
  pestaña, deja `Ln 4, Col 36` en la barra de estado y la selección valiendo exactamente `Product`.
- **El foco sobrevive:** escribiendo con el cursor en mitad de la palabra, tras el repintado queda
  `enfocado=search-query`, valor intacto y cursor en 4, con el nodo del `<input>` ya sustituido.
- **Una expresión regular a medias:** `Product(` en modo regex dice "La expresión regular no es
  válida — Invalid regular expression: /Product(/gi: Unterminated group", cero resultados y la caja
  sigue enfocada.
- **Desde la paleta**, como lo usaría una persona: "Buscar en los archivos · Editar · Ctrl+Shift+F"
  abre la vista `Buscar`, enfoca la caja y marca la herramienta `search` como activa.
- `npx electron . --menu-dump` → 10 secciones, `MENU_OK`, **ningún acelerador repetido**.
- `npx electron . --smoke-test` → `SMOKE_OK`; `npm test` entero en verde, con **1343 pruebas**
  (1269 antes) más las de empaquetado y las tres arquitecturas compilando y pasando sus pruebas.

---

### Iteración 30 — 2026-08-25 — Fase 21: la terminal es una terminal, y tres cosas que estaban rotas

**Objetivo:** dos fallos que se notan al primer minuto de uso y una funcionalidad que llevaba doce
fases pendiente por una decisión que había dejado de ser cierta.

Los fallos: una Web API generada por el propio DotForge arrancaba en el puerto 5000, por HTTP y en
Production, con el IDE diciendo que lanzaba el perfil `https`; y cerrar una pestaña con cambios sin
guardar dejaba el editor sin aceptar texto —admitiendo Retroceso y no las letras— hasta reiniciar la
aplicación, con la ventana además incapaz de cerrarse mientras el aviso estuviera en pantalla.

La funcionalidad: pestañas de terminal con intérprete de verdad.

**Hecho, archivo a archivo:**

- `src/shared/json-text.ts` (**nuevo**): `stripBom` y `parseJsonText`. Aplicado a los diez lectores
  de JSON ajeno: `launch-settings.ts`, `node-scripts.ts`, `settings-service.ts`,
  `startup-service.ts`, `solution-service.ts`, `updater-service.ts`, `ai/secret-store.ts`,
  `efcore.ts`, `toolchain-manifest.ts` y `vsix.ts`.
- `src/main/services/launch-settings.ts`: `servesHttps` y la prioridad de HTTPS en `selectProfile`.
- `src/main/services/dotnet-service.ts` y `src/main/ipc/register.ts`: `launchProfileArgs` y
  `resolveLaunchProfile`. `dotnet run` y `dotnet watch` nombran el perfil que van a lanzar.
- `src/renderer/views/confirm-dialog.ts` (**nuevo**): `askDialog` y `confirmDialog`. Sustituyen a
  `window.confirm` en las cinco confirmaciones del IDE.
- `src/renderer/editor-state.ts`: `ConfirmationLock` y `unsavedChangesMessage`.
- `src/renderer/views/editor.ts`: `confirmDiscard`, con el recálculo de editabilidad y el foco
  devuelto a Monaco en un `finally`.
- `src/renderer/index.ts`: `confirmClose` con tres respuestas y el pestillo `closing`.
- `src/shared/terminal-profiles.ts` (**nuevo**): el catálogo.
- `src/main/services/terminal-pty-service.ts` (**nuevo**): las sesiones.
- `src/renderer/xterm-bridge.ts` (**nuevo**) y `src/renderer/views/panel.ts`: las pestañas.
- `src/shared/contracts.ts`, `src/main/preload.ts`, `src/main/ipc/register.ts`: cinco canales y dos
  eventos nuevos.
- `scripts/build.mjs`, `electron-builder.yml`, `src/renderer/static/index.html`: xterm en el vendor y
  `node-pty` fuera del asar.
- `src/main/main.ts`: `--ui=unsaved`, `--ui=terminal-pty` y la limpieza de sesiones al salir.
- Pruebas: `tests/unit/terminal-profiles.test.mjs` (**nuevo**), `tests/unit/pty-session.probe.mjs`
  (**nuevo**), `tests/unit/launch-settings.test.mjs`, `tests/unit/editor-state.test.mjs`,
  `tests/security/hardening.test.mjs`, `tests/package/packaging.test.mjs`.

**Decisiones registradas:** ADR-058 (marca de orden de bytes, perfil HTTPS y `--launch-profile`) y
ADR-059 (pseudoterminales con `node-pty` como dependencia opcional).

**Errores encontrados y solucionados:**

1. *Síntoma:* con las pruebas de sesión dentro de `node --test`, las 24 pasaban en verde y el proceso
   no terminaba nunca; a los 200 s la suite se declaraba fallida sin decir qué.
   *Causa raíz:* al matar una sesión de ConPTY, node-pty lanza un ayudante
   (`conpty_console_list_agent`) para enumerar los procesos de la consola, y ese ayudante deja vivo
   el bucle de eventos del padre. Es el tercer caso de la misma familia en este proyecto, después de
   la prueba de humo de Electron y del servidor HTTP sin cerrar.
   *Arreglo:* las que abren un intérprete viven en `tests/unit/pty-session.probe.mjs`, que es un
   proceso aparte y sale con `process.exit`. La prueba lo lanza y comprueba lo que imprime.
2. *Síntoma:* las pseudoterminales funcionaban en la aplicación y las pruebas las declaraban no
   disponibles, así que se saltaban solas. Verde diciendo que no hay nada que probar.
   *Causa raíz:* `typeof require === 'function' ? require : otraCosa`. En el bundle ESM, esbuild
   reescribe `require` por un sustituto que **pasa el `typeof`** y lanza al llamarlo ("Dynamic
   require is not supported"), así que se elegía siempre el camino roto.
   *Arreglo:* `createRequire` con ancla explícita —junto al bundle y, si no, el directorio de
   trabajo— y sin tocar el identificador `require`. Anotado en `CLAUDE.md`.
3. *Síntoma:* el menú del botón `+` ofrecía "PowerShell 7" en un equipo sin PowerShell 7; al
   pulsarlo, el panel saltaba a Salida con un error y la terminal desaparecía de la vista.
   *Causa raíz:* `availability()` sólo comprobaba `node-pty`, no el intérprete concreto. El catálogo
   declara más perfiles de los que suele haber instalados.
   *Arreglo:* `programExists` busca por `PATH` (con `PATHEXT` en Windows) y el canal
   `terminal:profiles` marca el perfil como no disponible **con su motivo**, en vez de dejar que el
   fallo llegue después y en otro panel.
4. *Síntoma:* `--ui=terminal-pty` no abría nada y no daba ningún error.
   *Causa raíz:* pulsaba el primer perfil cuyo texto contuviera "PowerShell", que tras el arreglo
   anterior era el deshabilitado.
   *Arreglo:* el modo de diagnóstico pulsa el primero **habilitado**, que es lo que haría una
   persona.
5. *Síntoma:* un `` escrito a mano acabó en `panel.ts` como carácter ESC literal, invisible.
   *Causa raíz:* la trampa de siempre —contrabarras a través del shell—, esta vez al revés: el
   heredoc se comió el escape y lo que llegó al archivo fue el carácter de control.
   *Arreglo:* reescrito con la herramienta de edición. Y una comprobación de caracteres de control
   sobre los archivos tocados, que encontró un segundo caso en `terminal-pty-service.ts`.

**Lo que no se ha hecho, y por qué:** las pestañas de terminal **no se persisten** entre sesiones.
Reabrir tres PowerShell al arrancar el IDE parece cómodo hasta que uno de ellos estaba en mitad de
algo; y "restaurar" una terminal es, como mucho, volver a abrirla vacía en el mismo directorio, que
no es restaurar nada. Tampoco hay perfiles definidos por el usuario: el catálogo es fijo. Añadir uno
propio (un WSL concreto, un `cmd` con variables de entorno) es una funcionalidad con su interfaz y
su persistencia, y a medias sería un archivo de configuración escondido.

**Verificado sobre la aplicación real**, con una solución Clean generada:

- **El aviso de cambios sin guardar, por los dos caminos.** Tras "Seguir editando":
  `readOnly=false`, foco en `native-edit-context` y `trigger('type')` inserta tres caracteres. Tras
  "Cerrar sin guardar": 0 pestañas, y al reabrir un archivo se vuelve a escribir. Antes, cualquiera
  de las dos respuestas dejaba el editor mudo.
- **Un `echo` de ida y vuelta en PowerShell:** escrito con el teclado sobre el emulador, ejecutado
  por el intérprete y con el prompt de vuelta debajo.
- **Tres pestañas a la vez** —asistida, PowerShell, símbolo del sistema, PowerShell 2— con la
  numeración por perfil, y cerrando una sola sin tocar las demás.
- **Cero procesos huérfanos** al salir: `OpenConsole.exe` a cero y el recuento de `powershell.exe`
  igual que antes de arrancar.
- **El perfil que se ofrece es el que hay:** "PowerShell 7" aparece deshabilitado y con el motivo,
  porque `pwsh.exe` no está instalado en este equipo.
- `npx electron . --menu-dump` → **ningún acelerador repetido** con "Nueva terminal" dentro.
- `npm test` entero en verde: **1318 pruebas unitarias** (1290 antes) más seguridad, empaquetado y
  las tres arquitecturas compilando y pasando las suyas.

### Iteración 31 — 2026-08-25 — Auditoría de estado, y el empaquetado roto por la Fase 21

**Objetivo:** auditar en qué estado quedó la v2.5.0 antes de abrir el siguiente ciclo, y decidir el
próximo hito con datos y no con la lista de deseos.

**Lo que la auditoría encontró:**

1. **El empaquetado estaba roto**, y lo rompió la Fase 21. `npm run dist:win` moría con
   `Could not find any Visual Studio installation to use`. El ADR-059 afirmaba "no hay paso de
   rebuild", y era cierto para **cargar** node-pty en ejecución —Node-API, binarios en el paquete—
   y falso para el empaquetador: electron-builder no comprueba si un módulo nativo trae binarios,
   ve la dependencia y lanza `@electron/rebuild` → node-gyp → Visual Studio. La suite entera estaba
   en verde y el producto no se podía empaquetar: ninguna prueba llegaba hasta ahí.
2. **`devlog.mjs status` borraba el campo que decía leer.** Sin argumentos llamaba a
   `setStatus('')` y dejaba en blanco el "Estado global" del encabezado. Es lo que lo tenía vacío
   desde algún punto entre la v1.0.0 y hoy, y volvió a pasar en directo durante esta auditoría.
3. **El motor de actualizaciones no tiene de dónde actualizarse.** El feed real
   (`/repos/sfedev/IDE-DOTNET/releases`) responde 200 con **cero releases**; el único tag publicado
   es `v2.1.0` y el workflow sube artefactos pero no crea la publicación. Ya estaba anotado como
   deuda en la Iteración 22 y sigue igual: el camino de actualización sólo se ha ejercitado con el
   estado simulado de `--ui=update`.

**Hecho:**

- `electron-builder.yml`: `npmRebuild: false`, con el motivo escrito en la cabecera y junto a la
  clave. El empaquetado vuelve a funcionar de punta a punta.
- `tests/package/packaging.test.mjs`: prueba que lo exige. Es la clase de línea que alguien quita
  "porque parece que no hace nada".
- `scripts/devlog.mjs`: `status` sin argumentos **lee**; con texto, escribe. Una cadena de espacios
  cuenta como vacía. Un documento sin línea de estado sale en rojo en vez de fingir que la ha
  escrito. `DEVLOG_FILE` permite apuntar a otro archivo, que es lo que hace falta para poder
  probarlo sin escribir en la bitácora de verdad.
- `tests/unit/devlog-script.test.mjs` (**nuevo**): 12 pruebas ejercitando el script como proceso
  contra una copia temporal, CRLF incluido.
- `PROJECT_DEVLOG.md`: estado global restaurado a v2.5.0 y ADR-059 corregido con la consecuencia
  que faltaba.
- `CLAUDE.md`: la trampa de electron-builder.

**Verificado sobre artefactos reales, no sobre la configuración:**

- `npm run dist:win` completo → `DotForge IDE-2.5.0-Setup-x64.exe` (120,4 MB) y
  `DotForge IDE-2.5.0-win-x64.zip` (165,6 MB). `npm run verify:dist` sin problemas.
- La **aplicación empaquetada** —no la de desarrollo— arranca (`SMOKE_OK`), sus perfiles de
  terminal contestan `powershell|ok`, `cmd|ok`, `lite|ok` y `pwsh|no: pwsh.exe no está instalado`,
  y una pestaña de PowerShell ejecuta `echo empaquetado-ok` y devuelve el prompt. Es decir:
  `node-pty` se carga desde `app.asar.unpacked` sin recompilarse.
- Open VSX contra el registro real: 156 resultados para "csharp"; hay una extensión de verdad
  instalada en `userData`.
- `update:check` contra el feed real: `up-to-date`, "Estás en la última versión (v2.5.0)".
- `npm test` en verde de punta a punta, con 12 pruebas nuevas.

**Sobre el backlog:** de los tres candidatos que se plantearon para este ciclo, dos ya estaban
hechos y verificados (actualizaciones y Open VSX, Fase 17). El único pendiente de verdad es la
persistencia de las pestañas de terminal. Y por delante de él hay algo que lo condiciona: **publicar
releases**, sin lo cual el actualizador es un motor sin combustible.

---

### Iteración 32 — 2026-08-26 — Publicar releases: el actualizador deja de ser un motor sin combustible

**Objetivo:** cerrar lo que la auditoría de la Iteración 31 señaló como bloqueante. El sistema de
actualizaciones in-app está terminado y probado desde la v2.1.0 —tarjeta flotante, descarga
verificada, instalación al cerrar, promesa persistida— y en nueve versiones **no ha ofrecido una
sola actualización a nadie**, porque no había ninguna release publicada que ofrecer. La CI construía
los binarios y los dejaba dentro del run, donde caducan a los 90 días y el IDE no los ve.

**Hecho, archivo a archivo:**

- `.github/workflows/release.yml`: job `publish` nuevo, con `permissions: contents: write` sólo en
  él y `contents: read` para el resto del workflow. Tres disparos que convergen —tag `v*`,
  `release: published` y `workflow_dispatch` con entradas `tag` y `draft`—, resolución del tag por
  variables de entorno (no interpolado dentro del shell), corte si el tag y `package.json` no dicen
  la misma versión, `gh release create`/`edit` + `upload --clobber`, y un último paso que le
  pregunta a la **API pública** si la release aparece con artefactos.
- `scripts/lib/release-notes.mjs` (**nuevo**): composición del cuerpo Markdown de la release. Puro,
  como `dist-artifacts.mjs`, y por el mismo motivo: decide un texto que ve el usuario.
- `scripts/release-notes.mjs` (**nuevo**): habla con `git` y con el disco. Resuelve el tag anterior
  por orden de versión (`--sort=-v:refname`, no por fecha), lee los artefactos de `dist/` y escribe
  las notas. Sirve a mano para ver qué se va a publicar antes de empujar el tag.
- `src/shared/github-api.ts`: `HeaderOptions.userAgent`.
- `src/main/services/updater-service.ts`: sus dos peticiones pasan por `requestHeaders` y su 403 por
  `rateLimitHint`.
- Pruebas: `tests/unit/release-notes.test.mjs` (**nuevo**, 22), `tests/package/packaging.test.mjs`
  (10 nuevas sobre el workflow), `tests/security/hardening.test.mjs` (el actualizador entra en la
  lista de adquisidores), `tests/unit/github-api.test.mjs`.

**Decisión registrada:** ADR-060 — la release la publica la CI con `gh`, y el tag manda.

**Errores encontrados y solucionados:**

1. *Síntoma:* la consulta del actualizador al feed iba **sin autenticar incluso donde había token**,
   o sea, con 60 peticiones por hora y por IP.
   *Causa raíz:* `updater-service.ts` escribía sus dos cabeceras a mano. Es el tercer módulo que
   hace el mismo par de peticiones que el depurador y el servidor de lenguaje —API de GitHub para
   preguntar, otro host para descargar—, pero nació después de que se escribiera la regla del
   ADR-050 y de la prueba estructural que la vigila, así que nadie lo metió en la lista. La regla
   estaba probada y el módulo que más falta le hacía quedaba fuera.
   *Arreglo:* las dos peticiones delegan en `requestHeaders`, que adjunta la credencial al feed
   (`api.github.com`) y **no** a la descarga del artefacto (`objects.githubusercontent.com`). El
   actualizador entra en la lista de adquisidores de `hardening.test.mjs`, con el motivo anotado
   ahí mismo para que la próxima incorporación no tarde otras nueve versiones.
2. *Síntoma:* ninguno todavía, y ése es el punto. Publicar un tag `v2.6.0` con los binarios de la
   `2.5.0` —que es lo que pasa si se etiqueta antes de subir la versión— dejaría al IDE ofreciendo
   la 2.6.0, instalando un 2.5.0, y encontrándose al arrancar con una instalación pendiente que
   sigue siendo posterior a la que corre. `initialize` sólo descarta lo pendiente cuando **no** es
   más nuevo, así que se reinstalaría en cada cierre indefinidamente, y no hay nada que el cliente
   pueda hacer contra eso.
   *Arreglo:* la CI se para si el tag y `package.json` no coinciden, con el motivo escrito en el
   `::error::`. Hay una prueba que exige que ese corte siga ahí.
3. *Síntoma:* las notas podían salir vacías sin que nada fallara.
   *Causa raíz:* `actions/checkout` hace un checkout superficial por defecto, y las notas se componen
   del rango entre el tag anterior y éste. Sin historial, `git log` no devuelve nada y la release se
   publica igual, sólo que muda.
   *Arreglo:* `fetch-depth: 0` en el job que publica, con una prueba que lo exige.

**Lo que no se ha hecho, y por qué:** **no se ha publicado ninguna release todavía**. Empujar un tag
es una acción sobre el repositorio público que le corresponde decidir a quien lo mantiene, no a la
iteración que prepara el camino. Todo lo que se puede verificar sin publicar está verificado, y
abajo está dicho cómo. Tampoco se ha hecho la **persistencia de las pestañas de terminal**: sigue en
pie el argumento de la Fase 21 —restaurar una terminal es, como mucho, volver a abrirla vacía en el
mismo directorio, que no es restaurar nada—, y adelantarla por delante de lo que la desbloqueaba no
habría cambiado ese argumento.

**Verificado, y con qué:**

- **Los cinco caminos de resolución del tag, ejecutando el paso de verdad** con las variables de
  entorno de cada disparo: `push v2.5.0` → `2.5.0`, no-prelanzamiento; `release v2.6.0-rc.1` →
  prelanzamiento marcado; `dispatch v3.0.0`; `dispatch` sin tag → `v2.5.0` leído de `package.json`;
  y `push nightly` → salida 1 con `::error::"nightly" no es un tag SemVer`.
- **El paso de publicación, ejecutado contra un `gh` de mentira** que registra lo que se le pide:
  con la release inexistente hace `view` → `create --title "DotForge IDE v2.5.0" --target <sha>` →
  `upload --clobber`; con la release ya existente, `view` → `edit --notes-file` → `upload`; con un
  prelanzamiento en borrador añade `--prerelease --draft`; y con `dist/` vacío sale con 1 en vez de
  publicar una release sin nada que descargar. `builder-debug.yml` no se cuela entre los artefactos,
  y los nombres con espacios llegan enteros.
- **El YAML se parsea** y los cinco bloques de shell pasan `bash -n`.
- **Las notas reales de la v2.5.0**, generadas con `node scripts/release-notes.mjs --tag v2.5.0`:
  24 cambios desde `v2.1.0`, con el enlace de comparación correcto.
- **El contrato con la tarjeta del IDE, probado de verdad**: el cuerpo que compone la CI se pasa por
  `releaseNotesLines` —el mismo lector que usa la tarjeta— y se comprueba que no se queda vacío, que
  lo primero que se lee es la versión, que los cambios entran en las doce líneas que caben, que no
  sobrevive ni una marca de Markdown y que **ninguna línea del cuerpo se evapora al limpiarla**. Son
  dos módulos en carpetas distintas que no se importan y sólo se encuentran en producción.
- **El actualizador contra el feed real**, sobre la aplicación en marcha:
  `--probe="window.dotforge.updates.check(true)"` → `up-to-date`, "Estás en la última versión
  (v2.5.0)". Sigue funcionando con las cabeceras compartidas.
- `npx electron . --smoke-test` → `SMOKE_OK`.
- `npm test` entero en verde: **1353 pruebas unitarias** (1330 antes), 77 de seguridad, 76 de
  empaquetado y las tres arquitecturas compilando y pasando las suyas.

**Cómo se publica la próxima versión, ahora que se puede:**

```bash
npm version 2.6.0 --no-git-tag-version && git commit -am "v2.6.0" && git tag v2.6.0 && git push --follow-tags
```

---

### Iteración 33 — 2026-08-26 — Fase 23: el panel de terminal vuelve como se dejó

**Objetivo:** la segunda mitad del encargo, que la Fase 21 había dejado fuera con un argumento
escrito. El argumento sigue siendo cierto —restaurar una terminal es, como mucho, volver a abrirla
vacía en el mismo directorio— así que no se ha refutado: se ha convertido en un interruptor, con la
letra pequeña dicha en el propio ajuste.

**Hecho, archivo a archivo:**

- `src/shared/terminal-layout.ts` (**nuevo**): el modelo. `coerceIncomingLayout` (lo que manda el
  renderer), `coerceStoredLayout` (lo que hay en el disco), `isRestorable` y `restorablePlan`.
- `src/main/services/terminal-layout-store.ts` (**nuevo**): una entrada por solución en
  `userData/terminal-layouts.json`, poda por uso —no por antigüedad— y lectura con `parseJsonText`.
- `src/shared/contracts.ts`, `src/main/preload.ts`, `src/main/ipc/register.ts`: dos canales nuevos
  (`terminal:layout-save` y `terminal:layout-restore`) y el ajuste `restoreTerminals`.
- `src/renderer/views/panel.ts`: `restoreTerminals()` y `saveTerminalLayout()`, enganchado a abrir,
  cerrar y cambiar de pestaña.
- `src/renderer/index.ts`: la reapertura cuelga de `applySolution`, que es lo que distingue abrir
  otra solución de releer la misma.
- `src/renderer/views/settings.ts`: grupo "Terminal" con el interruptor y su nota.
- `src/main/testable.ts`, `src/main/main.ts`: exportación para las pruebas e inicialización.
- Pruebas: `tests/unit/terminal-layout.test.mjs` (**nuevo**, 26) y 2 de seguridad en
  `tests/security/hardening.test.mjs`.

**Decisión registrada:** ADR-061.

**Errores encontrados y solucionados:**

1. *Síntoma:* al reabrir la solución aparecían **cuatro** pestañas donde se habían guardado dos, y
   el archivo decía `["lite","lite","lite","powershell"]`. Cada reapertura añadía una asistida más.
   *Causa raíz:* el panel arranca ya con una pestaña asistida, y la restauración abría encima las
   guardadas. La retirada de la del arranque estaba puesta *después* y condicionada a que la
   disposición no incluyera una asistida — que es justo el caso más normal de todos. Y como al
   terminar se vuelve a anotar, la de más quedaba guardada: crecía una por apertura.
   *Arreglo:* la del arranque se retira **antes** de reabrir nada y sólo vuelve si no ha entrado
   ninguna. Se comprobó midiendo dos reaperturas seguidas: tres pestañas las dos veces y el archivo
   idéntico. La primera medición sobre la aplicación real lo cazó; ninguna prueba unitaria lo
   habría visto, porque el error estaba en el reparto entre el modelo y el panel, no dentro de uno.
2. *Síntoma:* tres pruebas del almacén en rojo diciendo que dos soluciones distintas devolvían la
   misma disposición.
   *Causa raíz:* la trampa de siempre, y van once: **contrabarras a través del shell**. El
   ayudante de las pruebas se escribió con un heredoc y `` `C:\repos\${name}` `` llegó al archivo
   con un solo nivel de escape, o sea `C:` + retorno de carro + `epos` + `${name}` **literal** —el
   `\$` deja de interpolar—. Las dos soluciones acababan en la misma clave. El error que se ve es
   "el almacén mezcla las entradas", que no se parece en nada a la causa.
   *Arreglo:* reescrito con la herramienta de edición y con `join()` en vez de una plantilla, más
   una revisión de todas las rutas del archivo, que encontró otras tres con `\a` comido.
3. *Síntoma:* `TS2367: This comparison appears to be unintentional because the types '1' and '0'
   have no overlap` sobre un `length === 0` perfectamente alcanzable.
   *Causa raíz:* el guardia de arriba (`length !== 1` ⇒ salir) deja el tipo de `length` fijado en el
   literal `1` para el resto de la función, y TypeScript no sabe que los `await` de en medio
   modifican el array.
   *Arreglo:* el guardia compara `> 1`, que no fija un literal.

**Lo que no se ha hecho, y por qué:** no se recupera el **histórico** de la sesión. Grabar la salida
y reproducirla al abrir pinta una sesión que parece viva y no lo está: el prompt de arriba responde
a un proceso que ya no existe. Y cambiar de solución con el IDE abierto **no** cierra las terminales
que hubiera: dentro de una puede estar corriendo un `dotnet watch`, y matarlo para reabrir una
pestaña vacía es un intercambio malísimo. Sólo se restaura sobre un panel intacto.

**Verificado sobre la aplicación real**, con una solución Clean generada:

- **Se guarda lo que hay:** abriendo una pestaña de PowerShell sobre la asistida, el archivo queda
  con `["lite","powershell"]`, `activeIndex: 1` y el `cwd` de la solución.
- **Se reabre lo guardado:** sembrado `["lite","powershell","cmd"]` con la tercera activa, al abrir
  la solución el panel enseña `Terminal asistida | PowerShell | [Símbolo del sistema]` — en orden y
  con la activa correcta.
- **Y no crece:** segunda reapertura seguida, las mismas tres pestañas y el archivo idéntico.
- **El interruptor manda:** con `restoreTerminals: false`, el panel abre sólo con la asistida y lo
  guardado sigue intacto en el archivo.
- `npx electron . --smoke-test` → `SMOKE_OK`.
- `npm test` entero en verde: **1379 pruebas unitarias** (1353 antes), 79 de seguridad, 76 de
  empaquetado y las tres arquitecturas compilando y pasando las suyas.

**Deuda anotada, no resuelta:** al arrancar, el registro dice `Roslyn LanguageServer 5.4.0-2.26177.7
(la fijada ya no está en el feed; la más reciente sin marcar como prueba)`. El ADR-040 dice que la
versión se fija y se verifica a mano, y la fijada ha desaparecido del feed: hoy se está usando una
elegida sola, que es exactamente lo que ese ADR existe para evitar. El camino de respaldo está
haciendo su trabajo y avisando; queda como primer candidato del próximo ciclo.

---

### Iteración 34 — 2026-08-27 — Fase 24: Claude Code en la terminal, y el ADR-048 cumplido

**Objetivo:** dos encargos que resultaron ser el mismo. Usar Claude Code dentro del IDE sin escribir
un host de extensiones, y hacer que lo que las extensiones aportan de forma declarativa —temas y
fragmentos— se consuma de verdad.

**Sobre la numeración:** el encargo pedía "Fase 22" y "ADR-060", pero los dos existen desde la
iteración 32 (publicación de releases), igual que la Fase 23 y el ADR-061. Esto es la **Fase 24** y
el **ADR-062**; renumerar habría pisado historia ya escrita.

**Lo que la auditoría encontró antes de tocar nada:** la extensión de Claude Code para VS Code usa
96 símbolos distintos de la API de `vscode`, y su interfaz **es un webview**. Eso no es volumen de
trabajo: es una decisión de seguridad contra la CSP del renderer. La CLI, en cambio, sólo necesita
una terminal de verdad, y eso existe desde la v2.5.0. Y de paso: el IDE **no consumía nada** de las
extensiones instaladas, ni siquiera lo que su propia ficha listaba como soportado.

**Hecho, archivo a archivo:**

- `src/shared/terminal-profiles.ts`: perfil `claude`, `launchCandidates`, `resolveLaunch` y
  `unavailableReason`. Un perfil puede declarar alternativas; todas salen del catálogo.
- `src/main/services/terminal-pty-service.ts`: `resolveProgram` devuelve la ruta resuelta y `create`
  pasa a ser asíncrona (mirar el `PATH` toca el disco).
- `src/shared/terminal-cwd.ts` y `src/main/services/terminal-session.ts`: la orden `open-claude`.
- `src/shared/menu-template.ts`, `src/renderer/index.ts`: el comando y su atajo.
- `src/renderer/views/panel.ts`: `openOrFocusTerminal`.
- `src/renderer/terminal-suggest.ts`: la CLI y las órdenes de barra.
- `src/shared/vsix-contributions.ts` (**nuevo**) y
  `src/main/services/extension-contributions.ts` (**nuevo**): el consumo declarativo entero.
- `src/renderer/monaco-setup.ts`, `views/editor.ts`, `views/settings.ts`, `views/extensions.ts`: los
  temas registrados, aplicados, ofrecidos y recargados al instalar o desinstalar.
- `src/main/main.ts`, `src/main/ipc/register.ts`: `--ui=claude`, el canal de contribuciones y el
  modo de diagnóstico que ya no restaura terminales.
- Pruebas: `tests/unit/vsix-contributions.test.mjs` (**nuevo**, 36),
  `tests/unit/extension-contributions.test.mjs` (**nuevo**, 11), más las de perfiles, sugerencias,
  clasificación de líneas y dos estructurales de seguridad.

**Decisión registrada:** ADR-062.

**Errores encontrados y solucionados:**

1. *Síntoma:* la pestaña de Claude Code moría al abrirse con `Cannot create process, error code: 2`,
   después de que el menú la ofreciera como disponible.
   *Causa raíz:* en Windows, `npx` es `npx.cmd`. `programExists` lo encontraba probando las
   extensiones de `PATHEXT`, pero **`CreateProcess` sólo prueba `.exe`** al buscar por `PATH`: se
   comprobaba una cosa y se lanzaba otra.
   *Arreglo:* `resolveProgram` devuelve la ruta concreta y es esa la que se lanza. El error no
   nombra el programa ni la extensión, así que desde fuera parece un fallo de node-pty.
2. *Síntoma:* `npm test` fallaba en la prueba de humo con un timeout de 150 s, y la misma prueba
   pasaba lanzada sola. La aplicación imprimía `SMOKE_OK` y no terminaba nunca.
   *Causa raíz:* **la Fase 23**, con una disposición de terminal guardada. `--smoke-test` reabría
   las pestañas PTY de la última solución, y matarlas al salir lanza el ayudante de ConPTY de
   node-pty, que en un proceso sin consola falla con `AttachConsole failed` y deja vivo el bucle de
   eventos. Es la cuarta vez que esa familia de fallo cuelga algo en este proyecto.
   *Arreglo:* los modos de diagnóstico no restauran terminales. Es la misma regla que ya se aplicaba
   a la comprobación de actualizaciones, y estaba escrita tres líneas más arriba: "deben partir
   siempre del mismo estado".
3. *Síntoma:* se instala un tema oscuro de Open VSX, el editor se pone **blanco**, y no hay ningún
   error por ninguna parte.
   *Causa raíz:* dos fallos encadenados. `monaco.editor.defineTheme` **valida el nombre del tema** y
   lanza `Illegal theme name!` con cualquier cosa que no sean letras, dígitos y guiones — y el
   identificador (`ext:Telokis.theme-dracula-at-dusk:Dracula At Dusk`) lleva dos puntos, puntos y
   espacios. El tema no quedaba registrado; y `setTheme` con un nombre desconocido **no protesta**:
   cae al tema claro por defecto.
   *Arreglo:* `monacoThemeName` sanea el identificador y le pega un hash, porque el saneado pierde
   información. El identificador legible y el nombre interno son dos cosas distintas a propósito.
4. *Síntoma:* con el tema ya registrado, cambiarlo desde Ajustes no hacía nada.
   *Causa raíz:* `updateOptions({ theme })`. En Monaco el tema es **global** y esa opción se ignora
   en silencio (sólo se lee al crear el editor). El conmutador claro/oscuro llevaba funcionando de
   rebote desde siempre: `defineThemes` redefine el tema activo con los tokens CSS ya cambiados, así
   que el editor se repintaba **conservando el nombre**. En cuanto hay un tema que es otro nombre y
   no otra definición del mismo, eso deja de bastar.
   *Arreglo:* `monaco.editor.setTheme` explícito.
5. *Síntoma:* un `.tmTheme` se parseaba sin error y salía vacío.
   *Causa raíz:* un plist alterna `<key>` y su valor como **hermanos**, y fast-xml-parser sin
   `preserveOrder` los agrupa por etiqueta —todas las claves juntas, todas las cadenas juntas— y la
   correspondencia se pierde. Además el mensaje de error del servicio decía "apunta fuera de la
   extensión", que era falso: confundía "ruta inválida" con "no se ha podido interpretar".
   *Arreglo:* `preserveOrder: true` y emparejado por posición; y los dos motivos, separados.
6. *Síntoma:* tres pruebas del almacén de disposiciones en rojo — arrastrado de la iteración
   anterior y anotado aquí porque volvió a pasar: **contrabarras a través del shell**, esta vez en
   una ruta de mentira de Windows, donde la efe y la be van precedidas de contrabarra y son
   caracteres de control.
   *Arreglo:* rutas de mentira con barras normales, escritas con la herramienta de edición.

**Lo que no se ha hecho, y por qué:** no hay host de extensiones. Ejecutar el código de un `.vsix`
exige un proceso aparte, un módulo `vscode` que implemente esos 96 símbolos y —para esta extensión
en concreto— webviews, que es HTML de un tercero dentro de la ventana. Lo primero es trabajo
mecánico; lo segundo es una decisión de seguridad que merece su propio ADR el día que se tome. Y
tampoco se consumen las **gramáticas** TextMate: Monaco usa Monarch, y traducir una gramática de
TextMate exige `vscode-textmate` y el WASM de Oniguruma. Es una funcionalidad entera, no el paso
siguiente.

**Verificado sobre la aplicación real:**

- **Claude Code por la paleta**, que es como lo abriría una persona: `--ui=claude` deja la pestaña
  `[Claude Code]` abierta y activa, y a la segunda invocación **la enfoca en vez de duplicarla**.
- **Una sesión de verdad**: el programa lanzado es el `npx.CMD` de la instalación de Node, con
  `npm exec @anthropic-ai/claude-code` corriendo dentro. El perfil se ofrece disponible porque `npx`
  está, aunque `claude` no esté instalado en esta máquina.
- **Un tema real de Open VSX**: instalado `Telokis.theme-dracula-at-dusk`, 334 reglas de token
  convertidas y el fondo del editor medido en `rgb(14, 20, 25)` —que es su `#0e1419`—, con el resto
  de la ventana en `dotforge-dark`. Volviendo a "Ninguno" desde Ajustes, `rgb(27, 29, 39)`.
- **Fragmentos reales**: instalada una extensión de fragmentos de C#, escrito `dfxfa` en un
  `IClock.cs` de verdad y disparado el autocompletado: el widget de sugerencias enseña
  `dfxfact · dotforge.pruebas-csharp`. Las extensiones de prueba se han desinstalado al terminar.
- `npx electron . --menu-dump` → **ningún acelerador repetido** con `Ctrl+Shift+C` dentro.
- `npm test` entero en verde: **1448 pruebas unitarias** (1379 antes), 81 de seguridad, 76 de
  empaquetado y las tres arquitecturas compilando y pasando las suyas.

---

### Iteración 35 — 2026-08-27 — Estabilización de la v2.6.0: el IntelliSense vuelve a la versión fijada

**Objetivo:** cerrar la deuda que se venía arrastrando desde la iteración 33: el IDE arrancaba con
`Roslyn LanguageServer 5.4.0-2.26177.7 (la fijada ya no está en el feed…)`, es decir, con una
versión **elegida sola** — justo lo que el ADR-040 existe para evitar.

**El diagnóstico que se dio por bueno era falso, y lo decía el propio IDE.** El encargo partía de que
la versión fijada había sido retirada del feed, que es lo que anunciaba la barra de estado.
Preguntando al feed de verdad: publica **763 compilaciones** —el número exacto que documenta el
ADR-040— y `4.14.0-3.26423.7` **está entre ellas**. Lo que había era un veto de cuarentena en este
equipo, escrito el 25 de agosto, y `describeSelection` traducía ese estado con la frase de otro.

Antes de tocar la constante se hizo lo que el ADR-040 llama verificar: **lanzar el servidor**. La
versión fijada arranca, compone su gráfico MEF, aguanta 25 s sin un solo `fail:` y contesta por
stdio. No tenía nada malo. Subirla habría sido cambiar una versión sana por otra para tapar un veto
obsoleto.

**Hecho, archivo a archivo:**

- `src/main/lsp/lsp-client.ts`: `paramsField`, que omite `params` cuando no hay. Y con él la versión
  del IDE inyectable ya no manda `shutdown` con `null`.
- `src/shared/lsp-health.ts`: `QuarantineEntry.ideVersion`, `quarantinedVersions` filtrando por ella
  y `staleQuarantineEntries` para poder decir qué vetos han caducado.
- `src/shared/lsp-versions.ts`: motivo `quarantined`, con su frase, y la distinción entre "vetada
  aquí" y "ya no está publicada".
- `src/main/lsp/acquire.ts`: `setIdeVersion`, el filtrado del veto y el aviso por consola de cada
  veto caducado que se reintenta.
- `src/main/main.ts`: `setIdeVersion(app.getVersion())` al arrancar.
- `src/main/toolchain.ts`: exportación de `staleQuarantineEntries` para las pruebas.
- `tests/unit/lsp-acquire.test.mjs`: 19 nuevas — el contrato del ADR-040, los motivos de la
  selección y la caducidad de los vetos.

**Decisión registrada:** ADR-063.

**Errores encontrados y solucionados:**

1. *Síntoma:* el IDE usaba una versión de Roslyn elegida sola y decía que la fijada ya no estaba en
   el feed.
   *Causa raíz:* la fijada estaba en cuarentena en este equipo, y el motivo `stable` —"la fijada ya
   no está en el feed"— se emitía también para ese caso. Son dos estados opuestos: en uno la versión
   sigue publicada y en el otro no, y sólo en el primero tiene sentido levantar el veto.
   *Arreglo:* motivo `quarantined` con su propia frase. La regla general queda anotada: **un estado
   degradado tiene que decir cuál de sus causas se ha dado**, no la más probable.
2. *Síntoma:* el servidor de Roslyn moría con `0xE0434352` —excepción .NET no controlada— en vez de
   cerrarse, con `Unhandled exception. System.InvalidOperationException: Unexpected value kind:
   Null` en `StreamJsonRpc.SystemTextJsonFormatter.JsonRpcRequest.CountArguments`.
   *Causa raíz:* `requestOn(child, 'shutdown', null)`. En LSP `shutdown` no lleva parámetros, y
   **omitirlos no es lo mismo que mandar `null`**: StreamJsonRpc cuenta los argumentos de la
   petición nada más deserializarla, y lo hace fuera de cualquier `try`.
   *Cómo se encontró:* la sonda escrita para verificar el servidor tenía el mismo fallo, así que lo
   mató. La primera lectura fue "la versión fijada está rota" — que es exactamente la conclusión
   equivocada que llevaba nueve meses en el archivo de cuarentena.
   *Arreglo:* `paramsField` en el punto donde se componen los mensajes, no en la llamada.
3. *Síntoma:* ninguno visible, y ése es el problema. Un veto de cuarentena era **permanente**.
   *Causa raíz:* la única salida (`pardonRoslynVersion`) sólo se dispara cuando la auditoría
   demuestra que la copia estaba corrupta. Un veto escrito por un bug del cliente —que es lo que han
   sido dos de los tres fallos documentados— no se levanta jamás, y el usuario se queda con una
   versión elegida sola sin saberlo.
   *Arreglo:* la entrada lleva la versión del IDE que la dictó y sólo bloquea mientras esa versión
   sea la que corre. Caduca; no se borra.

**Lo que no se ha hecho, y por qué:** no se ha subido la versión fijada. Era lo que pedía el
encargo, y habría sido tapar el problema: la fijada está publicada y funciona, comprobado
lanzándola. Tampoco se ha tocado la política de bandas del ADR-040 —`4.14.0` sigue eligiéndose
porque su `runtimeconfig.json` declara `net9.0` con `rollForward: Major` y arranca con el runtime 9
o el 10—, ni se ha añadido una acción de interfaz para levantar un veto a mano: con la caducidad
por versión, el caso que la justificaba deja de existir.

**Verificado sobre la aplicación real:**

- **El feed, preguntado directamente**: 763 versiones para `win-x64`, la fijada presente, y la banda
  `4.14.0` viva con 57 compilaciones.
- **El servidor fijado, lanzado a mano** con el mismo handshake que hace el IDE: inicializa, sigue
  vivo a los 25 s, `fail:` en stderr = ninguno. Con `shutdown` mandado con `params: null`, muere con
  `0xE0434352`; omitiendo los parámetros, aguanta.
- **El IDE, al arrancar**: `4.14.0-3.26423.7 quedó descartada por DotForge (sin versión); se vuelve
  a probar con la 2.6.0`, y a continuación `Roslyn LanguageServer 4.14.0-3.26423.7 (versión fijada
  por DotForge)`.
- **Con la solución abierta**, tras 95 s: estado `ready`, leyenda semántica de **82 tipos** y un
  `textDocument/hover` contestado con C# de verdad (`namespace Acme`). Es la verificación completa
  que pide el ADR-040: descargada, extraída, arrancada y contestando.
- `npx electron . --smoke-test` → `SMOKE_OK`.
- `npm test` entero en verde: **1467 pruebas unitarias** (1448 antes), 81 de seguridad, 76 de
  empaquetado y las tres arquitecturas compilando y pasando las suyas.

**Estado de la v2.6.0:** lista para etiquetar. `package.json` dice 2.6.0, la suite está en verde, la
prueba de humo pasa y `node scripts/release-notes.mjs --tag v2.6.0` compone las notas. Publicar es
un `git tag v2.6.0 && git push --follow-tags`, y el workflow se para si el tag y `package.json` no
coincidieran.

---

### Iteración 36 — 2026-08-27 — Fases 25 y 26: publicar, esconder la barra y ordenar las pestañas
**Objetivo:** cerrar las cuatro cosas que faltaban para que el IDE sirva de punta a punta con una
solución de verdad abierta: **publicar** un proyecto sin salir a una terminal, **esconder** la barra
lateral para leer código, **distinguir** las pestañas de siete proyectos que abren cinco
`Program.cs`, y que una **ruta de archivo** en un diálogo se pueda leer entera.

**Hecho:**

*Fase 25 — publicación.*
- `src/shared/dotnet-publish.ts`: modelo puro. Opciones → argumentos, con las tres banderas que
  dependen del RID (`PublishSingleFile`, `PublishReadyToRun`, `PublishTrimmed`), el saneado de la
  ruta de salida y la composición de la carpeta del resultado.
- `publishProject` en `dotnet-service.ts`, por el canal de tareas, y canal IPC propio
  `dotnet:publish` **fuera** de `TASK_KINDS` (ADR-064).
- `publish-profile-store.ts`: últimas opciones por proyecto en `userData/publish-profiles.json`.
- `publish-dialog.ts`: modal propio con las casillas atenuadas y el motivo escrito al lado.
- "Publicar…" en el menú contextual de los proyectos ejecutables, y resumen en el panel con
  `[Abrir carpeta]` al final de la línea.

*Fase 26 — barra lateral, pestañas y modales.*
- `Ctrl+B`, menú **Ver > Barra lateral**, comando en la paleta con el alias
  `workbench.action.toggleSidebar`, botón atenuado en la cabecera y estado persistido.
- `src/shared/editor-tabs.ts`: proyecto de un archivo (prefijo de directorio más largo, por
  segmentos, insensible a mayúsculas) y color asignado y guardado por nombre.
- `workbench.editor.tabPosition` con tres valores, resuelto entero en CSS con áreas de rejilla.
- La ruta del aviso de cambios sin guardar deja de salirse del cuadro.

**Decisiones registradas:** ADR-064 y ADR-065.

> **Nota de numeración:** el encargo pedía ADR-063 y ADR-064. El 063 ya estaba ocupado por la
> caducidad de las cuarentenas de Roslyn (iteración 35, el mismo día), así que estos dos son el 064
> y el 065. Renumerar habría dejado en el aire las referencias que ya apuntan al 063 desde
> `CLAUDE.md` y desde el código.

**Errores encontrados y solucionados:**

1. *Síntoma:* en el aviso de cambios sin guardar, la ruta del archivo aparecía cortada por el borde
   del cuadro, sin forma de leer el resto.
   *Causa raíz:* un elemento flexible arranca con `min-width: auto` —"no encojas por debajo de tu
   contenido mínimo"— y el contenido mínimo de una ruta de Windows es la ruta entera: no tiene ni un
   solo punto por donde partirla. La columna de texto de la cabecera se negaba a encoger y el
   `overflow: hidden` del diálogo hacía el resto.
   *Cómo se midió:* con una ruta real de 153 caracteres, el párrafo llegaba a `x=1358` y el cuadro
   terminaba en `x=943`. 415 píxeles fuera.
   *Arreglo:* `min-width: 0` en la columna, `overflow-wrap: anywhere` en la ruta —no `break-all`,
   que parte también lo que sí se podía partir bien—, alto máximo con desplazamiento propio y
   `title` con la ruta absoluta. Sin el alto máximo, una ruta anidada de verdad empuja los botones
   fuera de la pantalla en una ventana baja y el diálogo pasa a no poder contestarse.
2. *Síntoma:* `--ui=publish-run` no hacía absolutamente nada. Ni diálogo, ni tarea, ni error. El
   modo `--ui=publish` funcionaba, así que el fallo parecía estar en la publicación.
   *Causa raíz:* el script del modo se compone concatenando, `UI_PUBLISH_SCRIPT` termina en `})()` y
   la concatenación producía `})()setTimeout(…)`. Error de sintaxis: `executeJavaScript` no ejecuta
   nada y el modo termina en silencio.
   *Arreglo:* el `;` que faltaba, y un comentario diciendo por qué está ahí. La regla general queda
   anotada: **un modo de diagnóstico que no dice nada es indistinguible de la funcionalidad rota que
   pretende comprobar.**
3. *Síntoma:* ninguno visible todavía, y por eso se arregló ahora. `dotnet-service.ts` tenía tres
   bloques de `spawn` casi idénticos, y el aviso de "no se ha podido ejecutar dotnet" sólo estaba en
   uno de los tres: un SDK ausente dejaba una instalación de paquete colgada sin decir nada.
   *Arreglo:* un único `spawnDotnet` por el que pasa todo lo que se lanza, con pestillo en el
   `finish` — un `error` de spawn puede venir acompañado de un `close`, y dos avisos de final para la
   misma tarea harían avanzar de dos en dos un paso de la instalación en varios proyectos.

**Lo que no se ha hecho, y por qué:**
- **No hay selector de color por proyecto en Ajustes.** El color se asigna solo por el hueco libre
  más bajo y se guarda; una interfaz para cambiarlo a mano es un formulario más para una decisión
  que nadie toma dos veces. Lo guardado es editable en `settings.json` si alguien quiere.
- **No hay arrastre para reordenar pestañas.** Es otra cosa —el orden, no el agrupamiento— y no
  estaba en el encargo.
- **`publish` no acepta `--no-build` ni `--no-restore`.** Son las banderas que convierten "publicar"
  en "publicar algo que a lo mejor no es lo que hay en el disco", y desde un botón eso no se ofrece.

**Verificado sobre la aplicación real:**

- **Publicación completa**: `--ui=publish-run` sobre una solución Clean generada con el wizard. El
  diálogo se abre sobre `Acme.Shop.Blazor` **saltándose las tres bibliotecas** —cuyo menú no ofrece
  la entrada, que es lo correcto—, con `net9.0` leído del `.csproj` y las tres casillas atenuadas
  con su motivo. `dotnet publish` termina en 5,8 s, los artefactos están en
  `bin/Release/net9.0/publish` (`Acme.Shop.Blazor.exe` incluido), el panel escribe
  `✓ Acme.Shop.Blazor publicado en …` con su botón **Abrir carpeta**, y las opciones quedan anotadas
  en `userData/publish-profiles.json`.
- **Tira de pestañas a la izquierda** (`--ui=tabs`): `tabs vertical position-left` sobre el
  contenedor y `main tabs-left` sobre la rejilla; el editor mide **900 px en un área de 900 px** —sin
  franja en blanco— y la marca de proyecto pinta `rgb(215, 143, 190)`, que es `--tab-project-4`.
- **Colores repartidos por el orden del `.sln`**: `Acme.Shop.Domain: 0`, `Application: 1`,
  `Infrastructure: 2`, `Blazor: 3`, `WebApi: 4`, `UnitTests: 5` en `settings.json`.
- **Barra lateral escondida** (`--ui=sidebar`): `body sidebar-collapsed`, la barra a 0 px y el editor
  ocupando **1184 px en un área de 1184 px**.
- **Ruta en el modal**: con una ruta fabricada de 480 caracteres, el párrafo se queda en `x=922`
  dentro de un cuadro que acaba en `x=943`, se recorta a 83 px con 171 px de contenido desplazable, y
  los botones siguen a 502 px en una ventana de 754.
- `npx electron . --smoke-test` → `SMOKE_OK`.
- `npm test` entero en verde: **1567 pruebas unitarias** (1467 antes), 88 de seguridad (81 antes), 76
  de empaquetado y las tres arquitecturas compilando y pasando las suyas.

**Estado de la v2.7.0:** lista para etiquetar. `package.json` dice 2.7.0, la suite está en verde y la
prueba de humo pasa. Publicar es
`git tag -a v2.7.0 -m "DotForge IDE 2.7.0" && git push --follow-tags`; el tag **tiene que ser
anotado** o el push sale en verde y no se publica nada, y el workflow se para si el tag y
`package.json` no coincidieran (ADR-060).

---

### Iteración 37 — 2026-08-27 — Fase 27: el actualizador deja de ser mudo en los dos extremos
**Objetivo:** que el gesto más intrusivo del IDE —cerrarse solo para instalar una versión nueva—
diga qué va a pasar antes de ocurrir y qué ha pasado cuando ya ha ocurrido. El actualizador
funcionaba desde la v2.1.0 y no contaba ninguna de las dos cosas.

**Hecho:**

*Antes de cerrar.* `applyConfirmation` y `applyActionLabel` (puros, en `src/shared/updates.ts`)
componen el aviso previo y el texto del botón a partir de `planKind`. Pulsar "Cerrar e instalar"
abre el modal propio —el asíncrono, el que no bloquea el renderer— con la duración, quién termina
el trabajo y si la aplicación vuelve sola. Donde la actualización no puede aplicarse sola, el botón
dice "Abrir instalador" y el aviso no promete ni silencio ni reapertura.

*Al volver.* `judgePending` dicta los cuatro veredictos sobre el `pending.json` que quedó en el
disco, y el arranque publica el resultado en `state.outcome`: el "✅ ¡Actualizado con éxito a la
vX!" con las novedades guardadas, o el "⚠️ La actualización a la vX no se completó" con las dos
causas posibles, la descarga intacta y el botón para reintentarlo. La evidencia es la versión que
corre comparada con la prometida, más un contador de intentos que se anota **al lanzar** el
instalador.

*Y lo que hacía falta para que las dos frases fueran verdad.* `--force-run` junto al `/S`, y la
instalación movida de `before-quit` a `will-quit`.

**Decisión registrada:** ADR-066.

> **Nota de numeración:** el encargo pedía el ADR-065, que ya estaba ocupado por la tira de
> pestañas coloreada por proyecto (iteración 36). Éste es el 066; renumerar habría dejado en el
> aire las referencias que ya apuntan al 065 desde `CLAUDE.md` y desde el código.

**Errores encontrados y solucionados:**

1. *Síntoma:* ninguno visible, y es el más grave de los tres. Con un archivo sin guardar, pulsar
   "aplicar" lanzaba el instalador y **dejaba el IDE abierto**: el aviso de cambios sin guardar
   aparecía después, y con "Seguir editando" la salida se anulaba mientras el instalador estaba ya
   reemplazando los archivos de la aplicación en marcha.
   *Causa raíz:* `before-quit` se emite al *empezar* a cerrar. El `beforeunload` del renderer llega
   más tarde y puede cancelar el cierre; el instalador, no.
   *Arreglo:* `will-quit`, que se emite cuando ya no queda ventana y la salida es un hecho. Es la
   misma promesa del ADR-046 puesta en el evento que de verdad significa "esto se cierra". La regla
   general queda anotada: **un evento que anuncia una intención no es un evento que anuncia un
   hecho**, y lo irreversible cuelga del segundo.
2. *Síntoma:* la tarjeta prometía "se vuelve a abrir al terminar" y no había forma de que fuera
   verdad. Un instalador NSIS **asistido** (`oneClick: false`, que es lo que declara
   `electron-builder.yml`) ejecutado con `/S` a secas instala y no relanza nada: el usuario que
   acaba de leer la promesa se queda con el escritorio vacío.
   *Arreglo:* `--force-run` junto al `/S`, que es la misma pareja de banderas que manda
   `electron-updater`. La regla: **cuando una frase de la interfaz depende de una bandera, la
   bandera es parte de la frase.**
3. *Síntoma:* cerrar el aviso de "✅ ¡Actualizado!" dejaba programada al cierre una instalación que
   ya no existía.
   *Causa raíz:* `dismiss()` ponía `applyOnQuit: true` incondicionalmente. Con una tarjeta que sólo
   hablaba de actualizaciones por venir tenía sentido; con una que también habla de las que ya
   pasaron, no.
   *Arreglo:* `applyOnQuit: pending !== null`, y una acción propia (`acknowledgeOutcome`) para
   cerrar la noticia. Cerrar un mensaje y posponer una instalación son dos verbos distintos.

**Lo que no se ha hecho, y por qué:**
- **No se lee el resultado del instalador.** No se puede: se lanza `detached`, con `stdio:
  'ignore'`, a un suspiro de que el proceso padre desaparezca. Esperar a un hijo que va a reemplazar
  el ejecutable del padre es exactamente lo que el ADR-046 evita.
- **No hay una pastilla en la barra de estado.** El encargo la mencionaba como alternativa a la
  tarjeta. La tarjeta ya existe, ya sabe pintar notas de versión y ya está donde el usuario mira
  cuando hay una actualización; una segunda superficie diciendo lo mismo en dos sitios es peor que
  una.
- **Un plan `open` no puede declararse fallido.** En macOS, "se abrió el `.dmg` y todavía no se ha
  arrastrado nada" es el curso normal, no un incumplimiento.

**Verificado sobre la aplicación real:**

- **`--ui=update-done`**: `✅ ¡Actualizado con éxito a la v2.8.0!`, subtítulo
  `Ya estás en la v2.8.0. Esto es lo que trae:`, las cuatro líneas de notas, un solo botón
  ("Entendido") y la franja en `rgb(165, 140, 245)` — el acento.
- **`--ui=update-failed`**: `⚠️ La actualización a la v2.8.0 no se completó`, el mensaje entero con
  la versión en la que ha quedado el usuario, las dos causas, `Van 2 intentos.` y la nota de que la
  descarga sigue guardada; botones `Cerrar e instalar` / `Al cerrar` y la franja en
  `rgb(227, 196, 139)`, que es `--warning`.
- **`--ui=update-confirm`**, que pulsa el botón como lo pulsaría una persona: el modal sale con
  `Cerrar e instalar la v2.8.0`, el detalle completo y los botones `Ahora no` / `Cerrar e instalar`,
  con el foco en el segundo.
- `npx electron . --smoke-test` → `SMOKE_OK`.
- `npm test` entero en verde: **1597 pruebas unitarias** (1567 antes), 88 de seguridad, 76 de
  empaquetado y las tres arquitecturas compilando y pasando las suyas.

**Subida de versión:** `package.json` pasa a **2.8.0**. La v2.7.0 ya está etiquetada y empujada
(`v2.7.0` anotado en `origin`), así que estos tres commits van encima de una versión publicada y no
podían salir con su número: el actualizador decide si hay algo nuevo comparando el tag, y una
release cuyo `package.json` dijera 2.7.0 dejaría una instalación pendiente que sigue siendo "más
nueva" que la que corre — se reinstalaría en cada cierre, indefinidamente (ADR-060).

**Estado de la v2.8.0:** lista para etiquetar. `package.json` dice 2.8.0, la suite está en verde y
la prueba de humo pasa. Publicar es
`git tag -a v2.8.0 -m "DotForge IDE 2.8.0" && git push --follow-tags`; el tag **tiene que ser
anotado** o el push sale en verde y no se publica nada, y el workflow se para si el tag y
`package.json` no coincidieran (ADR-060).

**Mantenimiento posterior (misma sesión) — el runtime de las acciones de la CI.** Un run dejó un
aviso de que Node 20 está obsoleto y la primera lectura fue la equivocada: `node-version:` ya decía
24 en los tres jobs. El aviso hablaba del **otro** Node de un workflow, el que ejecuta las acciones
en sí y que declara cada una en su `action.yml`: las seis `actions/*@v4` corren en `node20`. Se
suben a las últimas (`checkout@v7`, `setup-node@v7`, `setup-dotnet@v6`, `cache@v6`,
`upload-artifact@v7`, `download-artifact@v8`), todas ya en `node24`, incluidas las del bloque de
macOS comentado — para que resucitarlo algún día no reintroduzca el runtime viejo.

Comprobado antes de tocar nada: que cada major nuevo declare `using: node24`, y que ninguno haya
renombrado los `with:` que usamos (`path`/`key`, `name`/`path`/`if-no-files-found`,
`dotnet-version`, `node-version`, `fetch-depth` siguen existiendo los seis). La prueba estructural
que exige que todo `uses:` sea `actions/*` no fija versiones, así que sigue protegiendo lo que
importa —que nadie de terceros corra con el permiso de escritura— sin estorbar la subida.

`package.json` gana `engines: { node: ">=24" }`. Se daba por supuesto en todas partes y no lo
declaraba nadie: quien clone con Node 20 se entera ahora al instalar, y no al fallarle una prueba
con un error que no menciona la versión.

**Pendiente de validar:** el par `upload-artifact` / `download-artifact` salta tres majors y ya
rompió compatibilidad una vez (v3 -> v4). Se valida en la iteración siguiente — y no con
`draft: true`, que era el plan y resultó no ser un ensayo seguro.

---

### Iteración 38 — 2026-08-27 — Validar en la CI la subida de las acciones a Node 24
**Objetivo:** comprobar en un run de verdad que `upload-artifact@v7` y `download-artifact@v8` se
entienden, sin que ningún usuario reciba nada. Era lo único con riesgo real de la subida: los dos
son una pareja y ya rompieron compatibilidad entre majors una vez.

**El plan era `draft: true`, y no servía.** Al leer el job de publicación antes de disparar nada
apareció el motivo: el paso es *crear-o-completar* y el `--draft` sólo viaja a `gh release create`.

```bash
if gh release view "$TAG" > /dev/null 2>&1; then
  gh release edit "$TAG" --notes-file release-notes.md   # <- rama "ya existe": el flag no llega
else
  gh release create "$TAG" ... "${flags[@]}"             # <- aqui, y solo aqui, va --draft
fi
```

Y el portillo de versión (ADR-060) obliga a que el tag coincida con `package.json`, que decía
`2.8.0`: justo la release **ya publicada**. O sea, el único tag admisible era el que entraba por la
rama de arriba. Un `workflow_dispatch` con `draft: true` no habría creado ningún borrador: le habría
reescrito las notas y reemplazado los binarios a la versión que los usuarios estaban viendo — lo
contrario de la garantía que el encargo pedía. Con cualquier otro tag, el portillo corta el job y no
hay tres jobs en verde que enseñar.

**Hecho:** un input `dry_run` que recorre el pipeline entero y se para antes de tocar nada.
Construye, sube los artefactos, los descarga en el job de publicación y compone las notas; los dos
pasos que escriben en GitHub quedan fuera con `if: inputs.dry_run != true`. Es exactamente donde
vive el riesgo —el traspaso ocurre **antes** de que entre `gh`—, así que valida lo que hay que
validar sin arriesgar nada. Con un paso que además lo dice: lista los binarios recibidos con su
tamaño y falla si `dist/` llega vacío; sin eso, un traspaso roto pasaría en verde, porque los pasos
que habrían protestado son justo los que el ensayo se salta.

Cuatro pruebas estructurales lo vigilan: que el input venga apagado, que ningún paso que escriba en
GitHub corra en ensayo, que el ensayo compruebe el traspaso y falle sin artefactos, y que vaya
después de descargarlos y no antes.

**Errores encontrados y solucionados:**

1. *Síntoma:* el primer vigilante del run informó de un ensayo "terminado" con un solo job y sin
   conclusión, y el run llevaba treinta segundos corriendo.
   *Causa raíz:* `gh run watch` salió en el acto, y su error iba a `/dev/null`. La comprobación de
   que la release no se había tocado se hizo, por tanto, **antes** de que existiera el job que podía
   tocarla: habría dado "verde" pasara lo que pasara después.
   *Arreglo:* sondeo explícito de `gh run view --json status` hasta `completed`, con las respuestas
   inesperadas impresas en vez de tragadas. Es la trampa que este mismo archivo ya tenía anotada
   —un diagnóstico mudo es indistinguible de lo que pretende comprobar— cometida por el vigilante.
2. *Síntoma:* el segundo vigilante iba camino de quedarse ciego a mitad.
   *Causa raíz:* sondeaba la API **sin autenticar** cada 20 s, y quedaban 8 peticiones de las 60 por
   hora y por IP. Es el 403 del ADR-050 mordiendo en local en vez de en CI.
   *Arreglo:* sondear con `gh`, que usa el token del usuario y tiene 5 000/hora.

**Verificado sobre la CI real** (run
[33105631850](https://github.com/sfedev/IDE-DOTNET/actions/runs/33105631850), `workflow_dispatch`
sobre `master` en `6fdba1d`, `tag=v2.8.0`, `dry_run=true`):

- **Los tres jobs en verde**: `Pruebas`, `Artefactos de Windows` y `Publicar la release`.
- **El traspaso, que era lo único en duda**: `Traspaso correcto — 2 artefactos recibidos del job de
  construcción`, con `DotForge IDE-2.8.0-Setup-x64.exe` (126 763 081 b) y
  `DotForge IDE-2.8.0-win-x64.zip` (174 258 920 b). `upload-artifact@v7` y `download-artifact@v8` se
  entienden. Las notas se compusieron enteras, con sus cuatro cambios y sus dos descargas.
- **Los dos pasos que escriben en GitHub, `skipped`** — no `success`, que es la diferencia entre no
  haber publicado y haber publicado sin enterarse.
- **La v2.8.0, intacta.** Se capturó su estado antes del ensayo y se comparó después: mismo
  `updated_at` (`18:42:19Z`) y **los mismos identificadores de artefacto** (`532721703`,
  `532721702`). Es la comprobación que de verdad zanja la duda: `gh release upload --clobber` no
  reutiliza ids, así que unos números iguales demuestran que nadie subió nada.
- **Ninguna release nueva y ningún borrador**: siguen siendo v2.8.0, v2.7.0 y v2.6.0, las tres
  publicadas y con dos artefactos cada una. No hubo nada que limpiar.
- `npm test` entero en verde, incluidas las cuatro pruebas nuevas del ensayo.

**Lo que no se ha hecho, y por qué:** no se arregla que la rama "ya existe" ignore el `--draft`. Es
un fallo real, pero tocar la lógica de publicación tiene su propio riesgo —mal hecho, convierte una
release publicada en borrador y la saca del feed— y no era lo que había que validar hoy. Queda
anotado aquí y en `CLAUDE.md`; el ensayo, que es lo que hacía falta, ya no depende de ello.

### Iteración 39 — 2026-08-30 — La alternativa de `claude` deja de ser muda

**Objetivo:** un reporte de "Claude CLI no está funcionando" con Claude Code perfectamente
instalado y una pestaña que tardaba muchísimo o fallaba sin decir nada.

**Diagnóstico.** El montaje del ADR-062 estaba bien: el catálogo, la resolución inyectada, `PATHEXT`
y la ruta ya resuelta. Lo que falló fue el entorno, y de una forma que nadie adivina:

1. `claude` se instaló con el instalador nativo, que lo deja en `~/.local/bin` y añade esa carpeta
   al `PATH` **del registro**.
2. `explorer.exe` llevaba en marcha desde antes de esa instalación. Windows congela el entorno de un
   proceso al arrancarlo, y todo lo que lanza hereda **ese** bloque, no el registro.
3. El IDE, abierto desde ese Explorador, recibió un `PATH` sin `~/.local/bin`.
4. `resolveLaunch` no encontró `claude`, ni `claude.cmd`, ni `claude.exe`, y **sí** encontró `npx`.
   Así que arrancó `npx --yes @anthropic-ai/claude-code`, que descarga otra copia de la red.

Comprobado sobre la máquina: el `PATH` que reparte el Explorador no tiene `.local\bin` y el del
registro sí; la carpeta global de npm está vacía y la caché de npx no tiene el paquete, así que
cada apertura era una descarga.

**El fallo no era la alternativa: era el silencio.** La cadena de respaldo hizo exactamente lo que
promete el ADR-062 —que quien tenga `claude` instalado de cualquiera de las tres maneras pueda
abrirlo—, pero al sustituir no lo dijo. El usuario tenía su instalación local y el IDE estaba usando
otra sin mencionarlo.

**Hecho:**
- `resolveLaunch` devuelve `ResolvedLaunch`: además de la ruta, **con qué se pidió lanzar**
  (`requested`) y si hubo sustitución (`substituted`). Hacía falta porque `file` trae la ruta ya
  resuelta y `C:\...\npx.CMD` no se parece en nada a "claude".
- `substitutionNotice()` compone el aviso: qué falta, con qué se ha arrancado, que eso no es la
  instalación local y qué hacer —reiniciar el IDE, y el Explorador o la sesión si se instaló con la
  sesión ya abierta—.
- El aviso viaja en `TerminalSessionInfo.notice` y el panel lo escribe en la pestaña **antes** de la
  primera línea del intérprete. Después queda enterrado bajo lo que npx esté descargando, que es
  justo cuando hace falta leerlo.
- Seis pruebas nuevas en `terminal-profiles.test.mjs`. Una comprueba que el aviso nombra **`claude`**
  y no `npx`: decir "no he encontrado npx" manda a mirar donde no toca.

**Verificado:** `npm run test:unit` en verde (1 604), `tsc --noEmit` limpio, y el servicio abriendo
intérpretes de verdad en un directorio temporal: `powershell` no trae aviso y `claude`, con el `PATH`
sin `.local\bin`, resuelve a `npx.CMD` **y trae el aviso entero**.

**Errores encontrados:**
- *Síntoma:* la prueba nueva reventaba con `SyntaxError: Invalid regular expression flags`.
  *Causa raíz:* la trampa ya anotada en la Iteración 38 —un heredoc se come un nivel de escapes—,
  esta vez sobre `/@anthropic-ai\/claude-code/`, que se quedó en `/@anthropic-ai/claude-code/`.
  *Arreglo:* escribir las expresiones regulares con la herramienta de edición, no a través del
  heredoc. Van ya tres veces.

**Lo que no se ha hecho, y por qué:** no se comprobó el aviso en la ventana real. El IDE instalado
estaba abierto y `requestSingleInstanceLock()` no tiene excepción para los modos de diagnóstico, así
que una segunda instancia se cierra sola. Cerrar el IDE del usuario para mirar una línea amarilla no
compensa: la cadena entera está cubierta por las pruebas y el servicio se ejercitó de verdad.

**Siguiente:** nada pendiente de esto. Si el bloqueo de instancia única molesta para diagnosticar,
merecería su propia decisión: hoy impide `--smoke-test` y `--probe=` con el IDE abierto.

### Iteración 40 — 2026-09-08 — Fase 28: copiar y pegar en las pestañas de intérprete

**Objetivo:** un reporte con dos partes: que `cls` no limpia en PowerShell ni en el símbolo del
sistema, y que pegar sólo funciona en PowerShell —en `cmd.exe`, `Ctrl+C` y `Ctrl+V` pintan `^C` y
`^V` y ya—.

**Diagnóstico del portapapeles.** xterm manda `Ctrl+C` y `Ctrl+V` al intérprete como U+0003 y
U+0016 y llama a `preventDefault()`, así que tampoco llegan a los `role: 'copy'` / `'paste'` del
menú. Que en PowerShell pegara era PSReadLine leyendo el portapapeles del sistema por su cuenta: la
funcionalidad dependía de qué programa hubiera detrás. Reproducido con teclas de verdad sobre la
ventana (`SendKeys` con la ventana del IDE activada): `C:\Git\Roadmap>^V`.

**Diagnóstico del `cls`: no reproducido.** Capturados los bytes que emite ConPTY al recibir `cls`,
con y sin salida larga previa: `ESC[H`, un `ESC[K\r\n` por fila y `ESC[3J` al final (borra el
histórico). xterm 6 aplica los tres. Sobre la aplicación —desarrollo y la 2.8.0 instalada—, `cls`
en `cmd.exe` y en PowerShell deja sólo el prompt, también con la vista desplazada hacia arriba
antes de teclearlo. Sin el contexto exacto de la máquina en la que falla (tamaño del panel, qué se
había ejecutado antes) no hay nada que arreglar, y arreglar a ciegas es como se rompen las cosas
que funcionan.

**Hecho:**
- `src/shared/terminal-clipboard.ts` (puro): `keyboardGesture` y `mouseGesture` dicen qué gesto es
  cada tecla y cada clic. `Ctrl+C` con selección copia; sin ella, interrumpe. `Ctrl+V`,
  `Ctrl+Shift+V` y `Shift+Insert` pegan; `Ctrl+Shift+C` y `Ctrl+Insert` copian; sólo cuenta
  `keydown`, porque xterm pasa `keypress` y `keyup` por el mismo manejador (ADR-067).
- En macOS el módulo devuelve `none` para todo: `Cmd+C` / `Cmd+V` ya los atienden los `role` del
  menú y xterm escucha los eventos `copy` y `paste` del DOM. `Ctrl+C` en un Mac es interrumpir.
- Botón secundario en Windows como en la consola: con selección copia y la suelta; sin ella pega.
- Canal `clipboard:read-text` / `clipboard:write-text` (texto plano) en `register.ts`, expuesto
  como `dotforge.clipboard`. `navigator.clipboard` no era una opción: la ventana deniega todos los
  permisos del navegador y leer el portapapeles es uno de ellos.
- `attachClipboard` en `xterm-bridge.ts`: `attachCustomKeyEventHandler` con `preventDefault()` en
  los gestos atendidos —sin eso el evento sigue hasta el acelerador del menú y `role: 'paste'`
  pega una segunda vez— y `contextmenu` sobre el contenedor de la pestaña.
- `PanelHost.platform()`: el panel no sabía dónde corría y el gesto depende de ello.
- 18 pruebas en `terminal-clipboard.test.mjs`: 15 del modelo y 3 estructurales (el enganche en
  `panel.ts`, el `preventDefault()` junto al `return false`, y que ningún archivo del renderer use
  `navigator.clipboard`).

**Verificado:** `npm run build`, `tsc --noEmit` limpio, `npm run test:unit` en verde (59 archivos).
Y con teclas de verdad sobre la ventana, en `cmd.exe`: `Ctrl+C` sin selección sigue interrumpiendo
(`echo A` cortado y prompt nuevo) y `Shift+Insert` pega `PEGADO123` **una sola vez**. `Ctrl+V` va
por el mismo camino del código; su única diferencia es el acelerador del menú, y que
`preventDefault()` lo apaga es justo lo que la línea base demostró (con xterm consumiendo la tecla,
el `role` no pegaba).

**Errores encontrados:**
- *Síntoma:* la sonda de teclas mandó `echo PRUEBA` + Intro al chat que el usuario tenía en
  primer plano. *Causa raíz:* `AppActivate` falló sin decirlo y `SendKeys` teclea en la ventana que
  esté delante. *Arreglo:* la sonda comprueba con `GetForegroundWindow` que la ventana activa es la
  del IDE antes de mandar nada, y devuelve el portapapeles que pisa. Anotado en las trampas.
- *Síntoma:* la sonda de `--probe=` tecleaba `echohola`: el espacio no llegaba. *Causa raíz:* xterm
  atiende las letras en `keydown` y los caracteres imprimibles sin tecla propia en `keypress` con
  `charCode`. *Arreglo:* teclear con `keypress` para todo lo imprimible.
- *Síntoma:* `.click()` sobre el perfil abría la pestaña sin foco y las teclas iban al `<body>`.
  *Causa raíz:* `renderTerminal` sólo toma el foco si el elemento enfocado está dentro del panel, y
  un clic sintético no mueve el foco. Es el comportamiento deseado para el usuario (una tarea de
  fondo no roba el cursor del editor); la sonda enfoca el `textarea` de xterm a mano.

**Siguiente:** si `cls` vuelve a aparecer, capturar en esa máquina el tamaño de la pestaña
(`document.querySelectorAll('.xterm-rows > div').length`) y la salida de `mode con`: un ConPTY con
más filas de las que xterm pinta es el único mecanismo por el que la secuencia capturada dejaría
texto en pantalla.

### Iteración 41 — 2026-09-08 — Fase 29: el IDE se quedaba sin poder abrirse tras actualizarse

**Objetivo:** un reporte de la v2.9.0 recién publicada, con dos partes: al actualizar desde la
aplicación, el IDE no volvió a abrirse con el aviso de "actualizado"; y además **no se podía abrir
de ninguna manera**, tampoco buscándolo en el explorador de archivos. Como referencia, el proyecto
DocGen —una aplicación WPF con instalador de Inno Setup— hace lo mismo y sale bien.

**Diagnóstico.** El rastro estaba en el disco y era muy raro: la carpeta de descargas del
actualizador conservaba el instalador de 126 MB y **no** tenía `pending.json`. Ninguna ruta del
código borra sólo ese archivo: la limpieza borra la carpeta entera. Es decir, el borrado empezó, se
llevó el archivo pequeño y murió en el grande.

Por qué: el instalador de NSIS **relanza el IDE antes de terminar de salir él**, así que el IDE
recién abierto dictamina "instalada" y borra la carpeta con el instalador dentro y en marcha.
Windows no deja borrar la imagen de un proceso vivo → `EPERM`. Y `force: true` no cubre eso: sólo se
traga que la ruta no exista.

A partir de ahí, la forma del arranque hace el resto. `await updaterService.initialize(...)` está en
mitad de `app.whenReady().then(async () => { … })`, **antes** de registrar el IPC, de instalar el
menú y de crear la ventana, y ese `then` no tenía `catch`. La excepción se llevó por delante todo lo
que venía detrás: proceso vivo, sin ventana y con el bloqueo de instancia única puesto. Sin ventana
no se emite `window-all-closed`, así que nadie cerraba nada; y con el bloqueo puesto, cada intento de
abrir el IDE chocaba con él y salía en silencio. De ahí las dos mitades del reporte, que resultaron
ser el mismo fallo.

**Lo que aportó DocGen.** Su `DiscardPending` envuelve el borrado en un `try/catch` de
`IOException`/`UnauthorizedAccessException` y sigue. Y su instalador declara `CloseApplications=yes`
y relanza la aplicación desde su propia entrada `[Run]`, con `nowait postinstall` y sin
`skipifsilent`. Las dos ideas se han traído: la limpieza no puede lanzar, y el instalador tiene que
esperar a que la aplicación se cierre en vez de correr una carrera con ella.

**Hecho:**
- `removeUpdatesDir()` no lanza nunca, reintenta —`rm` reintenta ante `EPERM`— y deja lo que no pudo
  borrar para el arranque siguiente, que ahora **recoge** la carpeta cuando no hay registro
  pendiente. Sin eso, un instalador huérfano de 130 MB se quedaba en el disco de por vida.
- `updaterService.initialize` va dentro de su propio `try`, y la cadena de arranque tiene un `catch`
  que informa con un cuadro de error y cierra el proceso (ADR-068).
- Una segunda instancia sale con `app.exit(0)` y no con `app.quit()`, que es una petición y deja el
  módulo ejecutándose — con `will-quit` lanzando instaladores por el camino.
- `second-instance` abre una ventana si no hay ninguna y el arranque ya terminó.
- El plan de instalación pasa `--updated` además de `/S --force-run`: es lo que hace que NSIS espere
  a que el IDE termine de cerrarse. Es el `CloseApplications=yes` de DocGen.
- 6 pruebas nuevas. Una reproduce el `EPERM` de verdad (en Windows no se puede borrar el directorio
  de trabajo de un proceso, que es la forma determinista de provocarlo) y comprueba que el arranque
  llega igualmente al aviso; dos son estructurales sobre la forma de la cadena de arranque.

**Verificado:** `npm run build`, `tsc --noEmit` limpio y `npm test` completo en verde (unit,
security, package y scaffold). Y sobre la aplicación real, antes y después, con un `userData`
aislado (`--user-data-dir`) y un instalador falso corriendo dentro de la carpeta de descargas:

| Código | Resultado |
|---|---|
| v2.9.0 publicada | `UnhandledPromiseRejectionWarning: EPERM`, sin ventana, colgado hasta matarlo |
| corregido | aviso `[updater] no se ha podido limpiar…` y `SMOKE_OK` |

**Errores encontrados:**
- *Síntoma:* la primera prueba del borrado decía que `rm` no fallaba. *Causa raíz:* el proceso hijo
  todavía no había arrancado cuando se intentó borrar; 700 ms no bastaban. *Arreglo:* comprobar que
  el hijo está vivo (`process.kill(pid, 0)`) antes de medir. Una prueba de una condición de carrera
  que no verifica la condición mide otra cosa.
- *Síntoma:* la primera puesta en escena no ejercitaba nada. *Causa raíz:* el registro pendiente
  decía versión `9.9.9`, que es **posterior** a la que corre, así que el veredicto no era "instalada"
  y la limpieza ni se llamaba. *Arreglo:* la versión del registro tiene que ser la que corre.
- *Síntoma:* dos intentos de escribir el guion de puesta en escena murieron con
  `Invalid Unicode escape sequence`. *Causa raíz:* la trampa de siempre —un heredoc se come un nivel
  de escapes— sobre rutas de Windows. *Arreglo:* la herramienta de edición. Van cuatro.

**Lo que no se ha hecho, y por qué:** no se ha borrado a mano el instalador de 126 MB que quedó en la
carpeta de descargas de este equipo. La v2.9.0 instalada no sabe recogerlo —la recogida es parte de
este arreglo—, así que desaparecerá solo en el primer arranque de la versión siguiente.

**Siguiente:** publicar la corrección. Importa el orden: el código que se rompe es el de la versión
**recién instalada**, así que actualizar de la 2.9.0 a la siguiente ya se beneficia del arreglo. Lo
que no se puede arreglar hacia atrás es el `--updated`, que lo manda la versión que se va.

### Iteración 42 — 2026-09-08 — Sumas SHA-256 en cada release y la firma cableada
**Objetivo:** darle a quien descarga el IDE algo con lo que comprobar el binario, y dejar la firma
Authenticode lista para el día que haya certificado. Sale de un aviso de Sophos Intercept X al
instalar la v2.9.1 en un equipo corporativo (ADR-069).

**Hecho:**
- `scripts/lib/checksums.mjs` — composición y lectura del `SHA256SUMS.txt`, puro y probado.
  Formato de `sha256sum` (dos espacios; se lee también el separador binario `*`).
- `scripts/checksums.mjs` — hashea en streaming y escribe, o compara con `--check`.
- `PUBLISHABLE_EXTENSIONS` / `isPublishableArtifact` suben a `scripts/lib/dist-artifacts.mjs`:
  eran la misma lista en dos scripts y ahora la necesitaban tres.
- Las notas de la versión mencionan el archivo, en una línea y sólo si existe de verdad.
- Workflow: se calculan y se verifican tras el traspaso de artefactos, antes de componer las notas,
  y se adjuntan **fuera** del array que decide si llegó algún binario.
- Firma: `signtoolOptions` con SHA-256 y sellado RFC 3161, sin certificado; `CSC_LINK` y
  `CSC_KEY_PASSWORD` llegan por `env:` al paso que empaqueta, y `verify-dist --require-signed` se
  activa sólo cuando el secret existe.
- `npm run checksums` documentado en `CLAUDE.md`.

**Verificado:** `npm run build`, `tsc --noEmit` limpio y la suite completa en verde (1 660 pruebas
unitarias, 100 de empaquetado). Y el script ejecutado de verdad, no sólo sus pruebas:

| Comprobación | Resultado |
|---|---|
| Sumas sobre los artefactos reales de la 2.8.0 (126 + 174 MB) | 0,56 s, `.blockmap` y `win-unpacked` fuera |
| `sha256sum -c SHA256SUMS.txt` del sistema | ambos `OK` |
| Un byte añadido a un artefacto | `--check` sale con 1 y nombra el archivo |
| Directorio sin artefactos publicables | sale con 1 y **no** escribe el archivo |
| Notas sin el archivo presente | no aparece ninguna mención a SHA-256 |
| Las notas pasadas por `releaseNotesLines` | la línea 10 se lee como una frase, sin barras ni marcas |

**Errores encontrados:**
- *Síntoma:* `allow_forking: false` devolvía 422 al blindar los repos públicos. *Causa raíz:* GitHub
  sólo permite desactivar los forks en repos privados de una organización. *Arreglo:* ninguno
  posible; se cubre por la vía que sí importa —nadie más tiene acceso de escritura— y se documenta.
- *Síntoma:* el script no admitía una ruta absoluta en `--dir`. *Causa raíz:* `join(root, dir)`
  cuelga una ruta absoluta de la raíz del repositorio en vez de respetarla. *Arreglo:* `resolve`.

**Lo que no se ha hecho, y por qué:** no se ha subido la versión ni se ha publicado nada — el
cambio está en el árbol de trabajo. Y no se ha tocado `author.email` (`dev@dotforge.local`), que
acaba en el `CompanyName` del ejecutable y no ayuda a la reputación del binario: es un cambio de
identidad del producto y se decide aparte.

**Ensayo antes de publicar** (`dry_run`, run 34242961037): en verde y **diciendo lo que validó**.
El empaquetado corrió por primera vez con `CSC_LINK` en el entorno —vacío— e imprimió "Sin
certificado: se empaqueta sin firmar"; llegaron los dos artefactos con sus 126 764 877 y
174 260 812 bytes; las sumas se calcularon y se verificaron contra el disco; y las notas
mencionaron el archivo. La v2.9.1 quedó intacta, comprobado por lo único que lo demuestra: sus
artefactos conservan el mismo `id` (`gh release upload --clobber` no los reutiliza).

También se reescribió el "Qué es" del README, que eran once párrafos ordenados por versión —y con
cuatro versiones sin mencionar— para contar qué hace el producto hoy. El historial pasa a una
sección propia, "Novedades", con una línea por versión. De paso salió a la luz que la sección de
actualizaciones seguía describiendo el botón "Reiniciar y aplicar", que el ADR-066 había cambiado
por "Cerrar e instalar" justamente porque el IDE no reinicia.

**Siguiente:** decidir sobre el certificado Authenticode, que es lo único que cierra el asunto de
Sophos y de SmartScreen. Con él, la única acción es crear dos secrets: el resto ya está cableado.

### Iteración 43 — 2026-09-08 — El primer SHA256SUMS.txt no servía para nada
**Objetivo:** arreglar el archivo de sumas que publicó la v2.9.2, que era correcto e inútil.

**Qué pasó:** la v2.9.2 salió publicada, con su `SHA256SUMS.txt` colgando y el workflow entero en
verde —incluido el `--check` que rehashea el disco y compara—. Al bajarse el instalador de la
release y verificarlo como haría cualquiera, `sha256sum -c` falló en las **dos** entradas:

```
sha256sum: 'DotForge IDE-2.9.2-Setup-x64.exe': No such file or directory
```

El hash era exacto (`dad164b9…` coincidía con el binario descargado). Lo que no coincidía era el
nombre: **GitHub renombra los assets al subirlos** y sustituye el espacio por un punto, así que el
manifiesto llevaba el nombre de compilación y el usuario tenía el de descarga.

**Por qué la CI no lo vio:** su `--check` corre sobre el `dist/` del runner, donde los nombres
todavía llevan espacio. Nada que ocurra **antes** de la subida puede detectar lo que la subida
cambia. Es el mismo agujero conceptual que el ensayo mudo del ADR-060, y la lección se generaliza:
un artefacto publicado sólo se verifica descargándolo.

**Hecho:** `publishedAssetName` en `scripts/lib/checksums.mjs`, aplicado en los dos caminos —al
escribir el manifiesto y al comprobarlo— para que `--check` siga comparando cosas comparables sobre
los archivos locales. Sólo se normaliza el espacio: `artifactName` no produce nada más, e inventar
el resto de la tabla de GitHub sería adivinar.

**Verificado:** además de las pruebas, la ida y vuelta completa sobre artefactos con el nombre real
(con espacio), copiados después con el nombre que pone GitHub: `--check` sigue en verde sobre los
locales y `sha256sum -c` del sistema devuelve `OK` en los dos sobre los "descargados".

**Errores encontrados:**
- *Síntoma:* la verificación de la release recién publicada falló entera. *Causa raíz:* el
  renombrado de assets de GitHub. *Arreglo:* normalizar el nombre publicado. Anotado en las trampas.

**Siguiente:** publicar la 2.9.3 — la 2.9.2 se queda con un archivo de sumas que no se puede usar,
y no se puede reemplazar sin reescribir una release que ya está publicada.