Etapa 4 — Implementación

Precondición transversal: deben existir directrices de arquitectura publicadas. Reglas firmes ya identificadas:
- Backend expone información de forma agnóstica al consumidor (no se acopla a Front).
- Si Front necesita masticar datos, monta su propia capa BFF.
Input: outputs de Etapa 3 + HU/prototipo/propuesta técnica de Etapa 2.

Sub-etapas (orden y dependencias):

4.1 Diseño cierra

UX cierra el prototipo final, incorporando cualquier ajuste fino tras etapa 3.
UI (subagente del UX en fase 1; agente propio en fases posteriores) recoge el prototipo y entrega los diseños finales: composición visual, tokens aplicados, estados, componentes ya con paleta y tipografía definitivas.
Entregable: mockup visual interactivo navegable con mock data — no wireframes estáticos. El stakeholder debe poder navegar las pantallas principales y ver la línea gráfica real (color, tipografía, componentes, espaciado). Sin lógica funcional, sin estado real, sin datos reales — solo el aspecto visual del producto sobre datos de ejemplo hardcoded.

Formato canónico del entregable (decisiones 2026-05-22, actualizado 2026-05-22): el output del 4.1 tiene dos partes, ambas obligatorias.

Parte A — Guía de estilos del sistema de diseño (núcleo del entregable):

Una página interactiva navegable (página /styleguide dentro del propio repo de código, accesible desde la URL local del mockup) que cataloga todos los elementos del sistema de diseño independientemente del producto concreto. Esto es lo que el stakeholder valida principalmente. Cubre:

Paleta de colores: swatches con token semántico + valor hex + descripción de uso.
Tipografía: familia + escala completa + pesos + line-heights, con muestras de texto.
Espaciado: escala completa visualizada con bloques.
Radios y sombras: ejemplos con dimensiones declaradas.
Iconografía: set de iconos en uso.
Botones: todas las variantes (primary, secondary, success, danger, ghost, link) × estados visibles (default, hover, focus, active, disabled) × variantes de tamaño/icono.
Inputs y formularios: text input, textarea, checkbox, radio, select, con sus estados (focus, error, disabled) — incluir aunque el proyecto concreto no los use, para validar que el sistema cubre los casos típicos.
Componentes específicos del producto: cada uno con su markup en vivo (Header, Footer, Cards, Modal con backdrop, etc.).
Banners y estados especiales: warning, info, error full-screen, loading, empty state.
Patrones de layout: container max-width, breakpoints declarados.

Parte B — Aplicación al producto concreto:

Screenshots por viewport (desktop / tablet / mobile) de las pantallas principales del producto aplicando el sistema. Generados con device emulation real (Playwright o equivalente).
Lista de pantallas implementadas vs pendientes (con HU origen).

Acta canónica acta-diseno.md v1+ (propietario UX/UI) que contiene:

Inputs declarados según regla de versionado 2026-05-21 (ux.md vN, hu.md vN, tecnica.md vN, funcional.md vN, directrices/usabilidad.md vN).
Parte A documentada: catálogo de tokens (colores, tipografía, espaciado, etc.) en formato tabla + screenshots de las secciones de la página /styleguide.
Parte B documentada: screenshots de las pantallas del producto (Parte B) por viewport.
Decisiones visuales tomadas durante la implementación (desviaciones del ux.md original con justificación).
URL local de /styleguide y del mockup del producto para la sesión de review.
Render PDF + HTML del acta subido a Drive en etapa-4-implementacion/ como snapshot inmutable de cada iteración del sub-gate.

Reutilización entre proyectos: la página /styleguide y su sistema de tokens se mantienen vivos entre proyectos del arnés. En proyectos posteriores el UX/UI agéntico arranca el sub-gate 4.2 por la styleguide (no por las pantallas), validando primero la dirección visual del sistema antes de construir el producto encima.

4.2 Sub-gate humano — Validación visual del stakeholder (decisión 2026-05-22)

El stakeholder valida la línea gráfica + diseño visual + flujos navegables del mockup interactivo entregado en 4.1.
Bloqueante: sin este gate firmado, Frontend NO PUEDE empezar la implementación. La razón es operativa: implementar el front con una línea gráfica que después se reabre por el stakeholder genera retrabajo masivo.
Backend (si el proyecto lo tiene) sí puede empezar en paralelo a este gate — su contrato sale de funcional.md + tecnica.md + HU, no del prototipo visual. Mientras el stakeholder valida la UI, el Backend ya está implementando.
Retroceso: si el stakeholder rechaza la línea gráfica, vuelve al UX/UI (no a Frontend) para reformular el prototipo final. Es una iteración acotada (UX/UI cierra una nueva versión del prototipo, sub-gate vuelve a firmarse).
En proyectos sin backend (frontend puro como vocab-1000) este gate es crítico: sin él, la etapa 4 no avanza en absoluto.

4.3 Backend implementa

Trabaja según funcional.md + HU + tecnica.md + directrices de arquitectura.
Documenta su trabajo para que Front y otros se integren según indique el Arquitecto.
Puede empezar en paralelo a 4.2 (no depende del sub-gate visual).
Tests son parte del deliverable — no son opcionales, no son deuda, no los hace el QA (CAL-048):
- Por cada endpoint implementado: test de integración con happy path + errores previsibles.
- Por cada función/método con lógica de negocio: test unitario.
- Sin estos tests, el código no está terminado. El PR no se acepta. La HU no se cierra ✅.

4.4 Frontend implementa (solo tras 4.2 firmado)

Con los diseños finales validados, desarrolla la implementación y se integra con Backend según contrato.
Aplica BFF si procede.
Tests son parte del deliverable — no son opcionales, no son deuda, no los hace el QA (CAL-048):
- Por cada componente interactivo implementado: test de componente (render, interacción, estado de error).
- Por cada flujo crítico de UI: test e2e del flujo completo.
- Por cada hook o función de store con lógica: test unitario.
- Sin estos tests, el código no está terminado. El PR no se acepta. La HU no se cierra ✅.

4.5 SRE provisiona y mantiene entornos

Desde el cierre del refinamiento (Etapa 3), provisiona el entorno stage (entorno único pre-producción donde se ejecutan integración, regresión, exploratorio, carga si aplica y validación de experiencia real). El entorno pro se provisiona también pero no recibe tráfico hasta la promoción autorizada en Etapa 5.
Puede empezar en paralelo a 4.1 y 4.2 — el trabajo de infra no depende del diseño.

4.6 Promoción

Trabajo del agente ejecutor en su entorno local → integración continua → despliegue automático a stage cuando el CI pasa en verde.
Las pruebas de integración entre módulos ocurren ya en stage. No hay un entorno intermedio “dev” provisto por SRE.

4.7 Cierre formal de fases por el Director (decisión 2026-05-23)

El Director del ciclo (humano en fase 1, agente en fases posteriores) mantiene un documento cumplimiento-plan.md dentro de proyectos/<proyecto>/etapa-4/ con una entrada por cada fase del plan de etapa 4.
Cada entrada lleva: estado (✅ completada / ⏳ en curso / ❌ pendiente / ⚠️ parcial con deuda documentada / 🚫 descartada con motivo), HU cubiertas, commit(s) que cierran la fase, tests que la verifican, fecha de cierre.
El estado ⚠️ parcial se usa cuando la fase está mayoritariamente cerrada pero queda deuda residual conocida y documentada (la deuda se registra como Issue del repo o tarea trazable). No es un “casi ✅” laxo: requiere descripción explícita de qué queda. El gate final de etapa 4 puede firmar con ⚠️ solo si el humano del gate documenta excepción aceptando esa deuda.
Una fase no completada no se evapora: queda visible y bloqueante. El gate final de etapa 4 no puede firmarse mientras existan fases en estado ⏳ o ❌ sin excepción documentada por el humano del gate.
El reordenamiento de fases (como el del sub-gate 4.2 del 2026-05-22) debe reflejarse en cumplimiento-plan.md en el momento del reordenamiento, no a posteriori.

Motivo (incidente piloto vocab-1000, 2026-05-23): las fases 6 (catálogo NGSL) y 7 (i18n + a11y) se saltaron sin que nadie las “tachara” oficialmente como pendientes. El plan de fases vivía como prosa en memory.md, no como contrato verificable. El Director (agente de fase 1: el propio asistente) no tenía un mecanismo formal de cierre.

Output: desarrollo desplegado en stage + mockup visual aprobado en 4.2 + cumplimiento-plan.md con todas las fases en estado ✅ (o excepción documentada) + suite de tests por cada HU implementada (CAL-048).
Gate final de etapa 4: validación humana antes de pasar a Etapa 5. Material mínimo del gate: acta de etapa 4 + cumplimiento-plan.md + acta con inventario de scope (CAL-045) + evidencia de tests verdes por HU (cobertura mínima CAL-013 cumplida). Una HU sin tests de sus CAs no puede aparecer como ✅ en el inventario de scope.
Retroceso:
- Desde 4.2: vuelta al UX/UI para reformular prototipo.
- Desde la integración en stage: por definir (qué pasa si la integración falla repetidamente).
- Desde el gate final con cumplimiento-plan.md incompleto: vuelta a la fase correspondiente (no a una etapa anterior).

El sub-gate 4.2 — validación visual del Stakeholder

A mitad de la Etapa 4, el arnés intercala un sub-gate humano para validar la dirección visual del producto antes de aterrizar el contenido sustantivo. El UX cierra una styleguide navegable (Parte A: catálogo completo de tokens y componentes; Parte B: screenshots por viewport aplicando el sistema sobre las pantallas principales) y un acta-diseno.md con render PDF y HTML subido a Drive. El PO redacta un correo S-2 al Stakeholder con resumen ejecutivo de la línea visual, los adjuntos y la URL del entorno de validación con la styleguide accesible.

El Stakeholder firma S-2 (aprobación) o rechaza con feedback. Si firma, la implementación continúa hacia el cierre de Etapa 4. Si rechaza, retroceso al UX dentro de la propia Etapa 4 (no se vuelve a Etapas 2 o 3): el UX reformula la propuesta visual sobre el feedback recibido y el sub-gate se reabre con una nueva iteración. El Bloque A de infraestructura no retrocede ante un rechazo de S-2.

Flujos alternativos

El Director rechaza el cierre de etapa al firmar D-3

Si al cerrar Etapa 4 el Director detecta que alguna fase del plan-implementacion.md queda en estado distinto de ✅ sin excepción documentada, o que el inventario de scope (HU implementadas vs HU planificadas) no se ha poblado correctamente (viola CAL-045), bloquea D-3 y devuelve al equipo responsable la fase incompleta. El equipo cierra la fase y el Director vuelve a evaluar.

Aparece un gap bloqueante técnico imprevisto durante la construcción

Si durante la implementación un agente ejecutor (Arquitecto, SRE, Frontend, Backend, UX) descubre una decisión técnica firmada D-1 que no se puede materializar (por ejemplo, una dependencia que ya no existe, un patrón que rompe en producción), abre cruce mid-Etapa-4 al Arquitecto. Si la decisión exige modificar el stack respecto a tecnica.md v1, se abre ADR del proyecto documentando la nueva decisión, la firma simbólica del Director sobre el ADR autoriza el cambio, y el plan-implementacion.md se ajusta con las fases nuevas necesarias.

Privacidad bloqueante dispara abort en la regeneración del manual

En proyectos cuyo entregable es documentación generada desde otras fuentes (como este propio manual), el script generador puede abortar si el validador de privacidad detecta un literal sensible. El procedimiento firme es afinar el diccionario de sustituciones o ampliar el patrón bloqueante — nunca relajar las regex ni saltarse el validador con flags de exclusión. Cada iteración deja constancia fechada en memory.md con el literal descubierto y la sustitución elegida.

Documentación generada en esta etapa

Artefacto	Propietario	Tipo
`etapa-4/plan-implementacion.md`	Arquitecto	Markdown
`etapa-4/cumplimiento-plan.md` (estado vivo de las fases)	Director	Markdown
`etapa-4/acta-diseno.md`	UX	Markdown
`etapa-4/renders/acta-diseno.{pdf,html}`	UX (snapshot inmutable a Drive — pieza S-2)	PDF + HTML
`etapa-4/screenshots/*`	UX (Parte B de la styleguide)	PNG por viewport
`etapa-4/correos/s2-*.txt`	PO (correo al Stakeholder y respuesta de firma)	Texto plano
Código del producto en el repo del producto	Arquitecto, SRE, Backend, Frontend, UX según fase	Source + tests
`adr/NNNN-<slug>.md` (si la implementación abre nuevas decisiones arquitectónicas)	Arquitecto	Markdown
`proyectos/<slug>/memory.md` (entradas fechadas por cierre de fase)	Cada agente al cerrar fase	Markdown