docs: refactor ADRs to separate decision from implementation details

[Scot3004]

Objetivo

Refactorizar ADRs existentes (001-013) para mantener decisiones agnósticas a detalles de implementación, siguiendo el patrón establecido en ADR-010 y ADR-014.

Por qué: Los ADRs no deben volverse obsoletos cuando cambia la implementación. Nombres concretos, rutas de archivos, y funciones específicas deben vivir en docs/architecture/, no en ADRs.

Estado Actual

Auditoría completada en la rama refactor/content-page-hierarchy:

Estado	Cantidad	ADRs
🟢 Puros	2	005 (Copilot), 014 (refactored)
🟡 Parcialmente acoplados	8	001, 002, 006, 009, 011, 012, 013
🔴 Muy acoplados (refactoring específico)	3	003, 004, 008

ADRs Prioritarios para Refactor

🔴 Rojo — Alto Impacto (refactor urgente)

ADR-001 — Framework i18n y router polimórfico

• Demasiado largo, lleno de detalles técnicos
• Contiene: src/config/sections.ts, componentes específicos, rutas exactas, tabla de archivos
• Refactor: Reducir a decisión pura ("Configuración centralizada + router dinámico"), mover tabla de componentes a anexo histórico en docs/adr/anexos/001-i18n-router-framework/

ADR-003 — Third-party Mocks

• Completamente acoplado a nombres de funciones: mockThirdParty, mockGiscus, mockYouTube
• Rutas específicas: tests/e2e/helpers/
• Refactor: Decisión pura = "abstraer mocks de third-party en E2E", mover código concreto a anexo

ADR-004 — Linting, any y convenciones

• Describe cambios específicos (tabla: "patrón eliminado | reemplazo" con interfaces concretas)
• Asume ESLint ya configurado (no cubre decisión de setup original)
• Status: superseded por ADR-013 (está muerta)
• Refactor: Transformar a decisión pura ("ban any, SRP en interfaces"), mover histórico a anexo

ADR-008 — Client-side Testing

• Nombres exactos: initSidebar(), openSidebar, closeSidebar, toggleSidebar
• Archivos específicos: src/client/themeToggle.ts, src/client/sidebar.ts
• Refactor: Decisión = "testear client-side con unidades aisladas", mover implementación a anexo

🟡 Amarillo — Mejora Secundaria

ADR-007 — Unificación i18n (decisión vs implementación anterior)

• Menciona: postId, extractCleanId, buildLocaleEntryMap, SEOHead, SiteLayout
• Refactor: Separar "decisión de centralizar dominio" de "cómo se implementó en código"

ADR-002, 006, 009, 011, 012 — Detalles operativos acoplados

• ADR-002: comandos CI específicos (vitest --run --coverage, playwright test)
• ADR-006: archivos concretos (src/content.config.ts, src/domain/post.ts)
• ADR-009: config de herramientas (.markdownlint.jsonc, scripts npm run)
• Refactor: Mover operativos a docs/architecture/ o anexos, mantener decisión pura

Plan de Acción

1. Fase 1: ADRs rojos (003, 004, 008, 001)

   • ADR-003: Extraer implementación de mocks a anexo
   • ADR-004: Convertir a decisión de principios, mover tabla histórica
   • ADR-008: Separar decisión de nombres de funciones
   • ADR-001: Reducir largo, mover detalles a anexos

2. Fase 2: ADRs amarillos (002, 006, 007, 009, 011, 012, 013)

   • Revisar y mover ejemplos concretos a anexos/archivos de arquitectura
   • Mantener decisión pura y agnóstica

3. Validación

   • npm run lint:md debe pasar en todos
   • Ningún ADR debe mencionar nombres concretos (clases, funciones, archivos específicos)
   • ADRs deben ser válidas como referencia incluso tras refactorizaciones futuras

Referencia: Patrón Correcto

Ver ADR-014 (refactored) como modelo:

• ✅ Contexto: problema abstracto (múltiples responsabilidades)
• ✅ Decisión: patrón abstracto (especialización por responsabilidad, Vista de Lista vs Detalle)
• ✅ Implementación: referencias a docs/architecture/PAGE_OBJECTS.md para mapeo concreto
• ✅ Consecuencias: impacto conceptual (SRP, mantenibilidad, type safety)

No menciona: ContentListPage, ContentPostDetailPage, rutas específicas

Referencias

• ADR-010: Plantilla estándar de ADRs (guía de contenido por sección)
• ADR-014: Ejemplo refactorizado (decisión-centric, agnóstico)
• docs/adr/SUPERSEDED.md: Recordatorio de ADRs superseded (001, 002 suponen 007, 013)

---

Etiquetas propuestas: docs, refactor, adr, architecture