docs(decisions): ADR-003 branch-based deployment

[ahincho]

ADR-003: Branch-based deployment (main + dev, 1 solo ambiente AWS)

Summary

Captura la decisión del equipo de NO usar Terragrunt ni 2 ambientes AWS separados, optando por branch-based deployment con main y dev en repos con código deployable.

Context

• El equipo propuso 2 ambientes AWS + Terragrunt.
• Análisis de trade-offs: overkill para TFP académico de 5 meses.
• Coste: $0-15/mes (1 ambiente) vs $120/mes (2 ambientes) vs $120/mes + 1 semana (Terragrunt).

Decision

Opción 1 — Branch-based + 1 solo ambiente AWS, con:

• dev → auto-deploy al ambiente compartido (tag Environment=dev)
• main → deploy con aprobación manual (tag Environment=prod)
• Branch protection: main estricta (1 CODE OWNER review, enforce_admins), dev más laxa
• Aplica a: 02-infrastructure, 03-backend, 04-frontend, 05-data-pipeline, 06-model-training, 08-deep-agent
• NO aplica a: 00-knowledge-base, 01-devops, 07-article, templates, .github

Consequences

• ✅ Coste AWS mínimo (~$30/mes)
• ✅ Sin curva de aprendizaje de Terragrunt
• ✅ Demo protegida (main congelada para sustentación)
• ⚠️ Sin staging real (mitigado: AWS Academy Lab es sandbox)
• ⚠️ DRY violation futura si se agregan 3+ ambientes (registrado)

Implementation Plan

1. ✅ Crear este ADR
2. ⏳ Crear rama dev en 02 y 03
3. ⏳ Branch protection para dev
4. ⏳ Workflows: dev=auto-deploy, main=manual
5. ⏳ Retarget PR chore(governance): refine CODEOWNERS + add REVIEW_PERMISSIONS #2 a dev
6. ⏳ Documentar en READMEs
7. ⏳ Replicar en 04, 05, 06, 08

cc @spark-match/product-owners

[FabiTaparaQuispe]

Revisado ✅ Me parece una muy buena decisión, sobre todo el análisis de costos (1 ambiente ~$30/mes vs. ~$120 con dos) y el evitar la curva de Terragrunt para un TFP. El flujo feature → dev → main (congelada para sustentación) me queda clarísimo. 🙌

Dos detalles menores que vi:

1. Ramas dev creadas en repos que el propio ADR excluye.
   La tabla dice que 00-knowledge-base, 01-devops y 07-article NO aplican el patrón (son solo docs/tooling), pero igual se les creó rama dev. ¿Fue intencional por consistencia, o conviene borrarlas? Si fue a propósito, actualizaría la tabla para que no se contradiga.

2. Link roto en Referencias.
   La primera referencia apunta a una ruta local (D:\UNI\Spark\BACKEND.md) que nadie más puede abrir. Sugiero quitarla o reemplazarla por el doc equivalente dentro del repo.

Y una consulta desde el lado de testing: mencionas smoke tests post-deploy en dev (curl a /health) — ¿los tomo yo como parte de testing? También me llamó la atención el riesgo que anotas de "no hay staging real: si dev falla, se rompe el ambiente compartido". ¿Valdría la pena definir un mínimo de checks obligatorios antes de mergear a dev?

Pequeño detalle: veo que ya está en dev aunque figuramos como reviewers pendientes. Sin problema por mí (es solo docs), lo comento nomás por consistencia con el ADR-002. 🙂

Por lo demás, apruebo 👍