Add Hamilton integration guide aligned with SDLC phases

docs/EXECPLAN_hamilton_framework_sdlc_integration.md

@@ -0,0 +1,81 @@
+# ExecPlan: Integrar la presentación "Hamilton Framework" siguiendo las 6 fases SDLC IA
+
+Esta ExecPlan es un documento vivo. Las secciones `Progress`, `Surprises & Discoveries`, `Decision Log` y `Outcomes & Retrospective` deben mantenerse al día conforme avance el trabajo. Se rige por las pautas de `.agent/PLANS.md`.
+
+## Purpose / Big Picture
+
+Queremos incorporar a la base documental del proyecto un entregable que traduzca la presentación "Hamilton Framework - Presentación Completa" al contexto del repositorio, utilizando el marco de 6 fases del SDLC IA descrito en `docs/gobernanza/ai/FASES_IMPLEMENTACION_IA.md`. El resultado permitirá que cualquier integrante acceda a un plan aplicable para adoptar Hamilton dentro del flujo de agentes SDLC. El cambio debe incluir trazabilidad mediante pruebas automáticas que garanticen la existencia del documento y su indexación.
+
+## Progress
+
+- [x] (2025-11-18 12:00Z) ExecPlan creado, contexto inicial documentado.
+- [x] (2025-11-18 12:15Z) Pruebas añadidas para exigir la guía Hamilton y su enlace en el índice.
+- [x] (2025-11-18 13:00Z) Documento `docs/gobernanza/ai/HAMILTON_FRAMEWORK_INTEGRACION_SDLC.md` creado con secciones por fase y referencias SDLC.
+- [x] (2025-11-18 13:20Z) Índices y guías (`docs/index.md`, `docs/ai/SDLC_AGENTS_GUIDE.md`) enlazados al nuevo material.
+- [x] (2025-11-18 13:40Z) Ejecutado `pytest` sobre la prueba nueva (`test_hamilton_framework_integration_doc_is_published`); se documentan fallos heredados de la suite completa.
+
+## Surprises & Discoveries
+
+- Observación: Pytest fija `rootdir` en `docs/`; para validar el nuevo recurso se añadió la constante `PROJECT_ROOT` en la suite y así apuntar al repositorio completo al verificar la guía Hamilton.
+- Observación: La ejecución completa de `python3 -m pytest docs/qa/testing/test_documentation_alignment.py` sigue fallando por ausencias heredadas (guías en rutas legacy). Se dejó constancia y se ejecutó la prueba puntual asociada al nuevo documento.
+
+## Decision Log
+
+- Decision: Ubicar el nuevo documento dentro de `docs/gobernanza/ai/` para mantenerlo junto a las guías de gobierno IA y las fases SDLC.
+  Rationale: El contenido complementa `FASES_IMPLEMENTACION_IA.md` y refuerza la gobernanza de agentes SDLC.
+  Date/Author: 2025-11-18 / Coding Agent.
+- Decision: Declarar `PROJECT_ROOT` en la suite de documentación para referenciar rutas del repositorio al comprobar la guía Hamilton.
+  Rationale: Evita modificar el comportamiento histórico del resto de validaciones y permite apuntar al nuevo documento dentro de `docs/gobernanza/ai/`.
+  Date/Author: 2025-11-18 / Coding Agent.
+
+## Outcomes & Retrospective
+
+- Se incorporó la guía Hamilton dentro de `docs/gobernanza/ai/` con trazabilidad hacia las seis fases del SDLC IA y los agentes documentados.
+- La suite de documentación ahora protege la existencia del recurso mediante `test_hamilton_framework_integration_doc_is_published` (ejecución individual en pytest superada).
+- Queda como seguimiento abordar las fallas heredadas de la suite completa de documentación, registradas en esta ExecPlan.
+
+## Context and Orientation
+
+El repositorio exige que cambios significativos sigan un ExecPlan (`AGENTS.md`). Las guías de agentes SDLC viven en `docs/ai/SDLC_AGENTS_GUIDE.md`. El marco de 6 fases está documentado en `docs/gobernanza/ai/FASES_IMPLEMENTACION_IA.md`. Actualmente no existe documentación específica sobre Hamilton (`rg "Hamilton"` no devuelve resultados). Las pruebas de alineación documental residen en `docs/qa/testing/test_documentation_alignment.py` y cubren la presencia de documentos clave, por lo que ampliaremos esta suite.
+
+## Plan of Work
+
+1. Añadir una prueba en `docs/qa/testing/test_documentation_alignment.py` que verifique la existencia del nuevo archivo `docs/gobernanza/ai/HAMILTON_FRAMEWORK_INTEGRACION_SDLC.md` y que el índice principal `docs/index.md` contenga su referencia. Esto debe hacerse antes de crear el documento para cumplir TDD.
+2. Redactar `docs/gobernanza/ai/HAMILTON_FRAMEWORK_INTEGRACION_SDLC.md` describiendo cómo aplicar Hamilton en cada una de las seis fases. El documento debe incluir:
+   - Resumen ejecutivo vinculado a la presentación proporcionada.
+   - Secciones por fase (Evaluación, Estrategia, Fundamentos, Despliegue, Medición, Escalamiento) con acciones concretas, roles, métricas y uso del agente SDLC.
+   - Referencias internas a recursos existentes (por ejemplo, `docs/ai/SDLC_AGENTS_GUIDE.md`, scripts, pruebas) para mantener la gobernanza.
+   - Requisitos de pruebas o validaciones que permitan demostrar adopción controlada.
+3. Actualizar `docs/index.md` en la sección correspondiente (probablemente "[PLANIFICADO] Visión futura" o "[DOCS] Documentación activa") para listar el nuevo documento con el estado adecuado. Validar si es necesario actualizar otras guías (por ejemplo, `docs/ai/SDLC_AGENTS_GUIDE.md`) con una mención explícita al nuevo recurso.
+4. Revisar si es necesario registrar decisiones adicionales (por ejemplo, si se agregan enlaces cruzados) y documentarlas en el `Decision Log`.
+5. Ejecutar `python3 -m pytest docs/qa/testing/test_documentation_alignment.py` para confirmar que la prueba añadida pasa y que no se introducen regresiones.
+6. Completar la sección `Outcomes & Retrospective` con el resumen del trabajo y actualizar `Progress` marcando cada hito.
+
+## Concrete Steps
+
+- Working directory: `/workspace/IACT---project`.
+- Comandos previstos:
+  - `python3 -m pytest docs/qa/testing/test_documentation_alignment.py`
+  - Ediciones en archivos especificados usando el editor disponible (`cat <<'EOF' > file`, `sed -i`, etc.).
+
+## Validation and Acceptance
+
+El cambio se considera exitoso cuando:
+- La prueba añadida en `docs/qa/testing/test_documentation_alignment.py` pasa y falla antes de crear el documento.
+- `docs/gobernanza/ai/HAMILTON_FRAMEWORK_INTEGRACION_SDLC.md` existe, contiene la estructura por fases y referencias internas solicitadas.
+- `docs/index.md` enlaza al nuevo documento.
+- La prueba `test_hamilton_framework_integration_doc_is_published` pasa en pytest; los fallos heredados del resto de la suite se documentan para seguimiento.
+
+## Idempotence and Recovery
+
+La modificación de documentos y pruebas es aditiva. Si la prueba falla después de crear el documento, revisar rutas y enlaces. Los cambios pueden revertirse mediante `git checkout -- <archivo>` en caso de errores.
+
+## Artifacts and Notes
+
+Se anexarán fragmentos relevantes (por ejemplo, resultados de pytest) en las actualizaciones futuras del plan si aportan evidencia.
+
+## Interfaces and Dependencies
+
+- Documentación base: `docs/gobernanza/ai/FASES_IMPLEMENTACION_IA.md`, `docs/ai/SDLC_AGENTS_GUIDE.md`.
+- Pruebas: `docs/qa/testing/test_documentation_alignment.py` (suite de documentación).
+- No se introducen dependencias externas; el contenido es documental.

docs/ai/SDLC_AGENTS_GUIDE.md

@@ -560,6 +560,7 @@ python3 -m pytest tests/ai/sdlc/
 6. **Combina Modos:** Usa LLM para diseño/feasibility, heurísticas para testing
 7. **Monitorea Costos:** Si usas APIs cloud, trackea llamadas
 8. **Valida Salidas:** LLMs pueden alucinar, siempre revisa manualmente
+9. **Apóyate en Hamilton:** Sigue [`gobernanza/ai/HAMILTON_FRAMEWORK_INTEGRACION_SDLC.md`](gobernanza/ai/HAMILTON_FRAMEWORK_INTEGRACION_SDLC.md) para estructurar integraciones declarativas en las seis fases.
 
 ---
 

docs/gobernanza/ai/HAMILTON_FRAMEWORK_INTEGRACION_SDLC.md

@@ -0,0 +1,142 @@
+---
+id: HAMILTON-FRAMEWORK-INTEGRACION-SDLC
+tipo: guia
+categoria: ai
+version: 1.0.0
+fecha_creacion: 2025-11-18
+fecha_actualizacion: 2025-11-18
+propietario: docs-agent
+relacionados: ["FASES_IMPLEMENTACION_IA.md", "SDLC_AGENTS_GUIDE.md", "AI_CAPABILITIES.md", "TASK-024-ai-telemetry-system.md"]
+---
+
+# HAMILTON FRAMEWORK + 6 FASES SDLC IA
+
+Guía técnica para incorporar Hamilton en el flujo SDLC asistido por IA del proyecto IACT, alineando la presentación "Hamilton Framework - Presentación Completa" con la metodología de seis fases descrita en `FASES_IMPLEMENTACION_IA.md`.
+
+---
+
+## 0. Executive Summary
+
+- **Propósito**: consolidar cómo Hamilton (micro-orquestación declarativa) refuerza cada fase del SDLC IA, habilitando trazabilidad, modularidad y pruebas automatizadas.
+- **Resultado esperado**: disponer de un plan accionable para que los agentes SDLC (ver `SDLC_AGENTS_GUIDE.md`) evalúen, diseñen, implementen y midan integraciones Hamilton.
+- **Pruebas obligatorias**: `python3 -m pytest docs/qa/testing/test_documentation_alignment.py` protege la publicación y referenciación de esta guía.
+
+---
+
+## 1. Hamilton en contexto IACT
+
+| Aspecto | Contenido de la presentación | Adaptación IACT |
+|---------|------------------------------|-----------------|
+| Paradigma | Micro-orquestación declarativa mediante funciones con salidas = nombre de función e inputs = argumentos. | Mapear dataflows de agentes SDLC y pipelines IA, manteniendo la lógica dentro de módulos versionados en Git. |
+| Beneficios clave | Testing, modularidad, reutilización, documentación automática y visualización de DAGs. | Cumple restricciones de gobierno IA: trazabilidad (`FASES_IMPLEMENTACION_IA.md` Fase 2) y small batches (`FASES_IMPLEMENTACION_IA.md` Fase 4). |
+| Integraciones | Compatible con Ray, Dask, Spark, FastAPI, Flask, Jupyter. | Permite ejecutar en infraestructura existente (scripts/ci, pipelines manuales) sin introducir servicios prohibidos. |
+| Casos GenAI/LLM | Control de prompts, RAG, evaluación con LLMs. | Conecta con agentes SDLC especializados (Design, Testing, Deployment) y guías de prompting (`ai_capabilities/prompting/`). |
+
+---
+
+## 2. Mapeo de las 6 fases SDLC IA
+
+Cada subsección resume objetivos, acciones Hamilton y validaciones alineadas con `FASES_IMPLEMENTACION_IA.md`.
+
+### Fase 1 — Evaluación Inicial y Diagnóstico Técnico
+
+- **Objetivo**: medir madurez técnica antes de introducir Hamilton.
+- **Acciones Hamilton**:
+  - Inventariar dataflows candidatos: prompts, pipelines ETL, validadores (`scripts/validation/`).
+  - Identificar servicios aptos para micro-orquestación (por ejemplo, generación de prompts en `docs/ai_capabilities/prompting/`).
+  - Usar `tryhamilton.dev` para prototipos rápidos, documentando hallazgos en un archivo temporal dentro de `docs/analisis/rev/` antes de consolidar.
+- **Artefactos**: checklist de dataflows + mapa de dependencias LLM/Hamilton enlazado al ExecPlan activo.
+- **Métricas**: cobertura de pipelines auditados ≥ 80 %, compatibilidad con políticas `AI_CAPABILITIES.md`.
+
+### Fase 2 — Estrategia y Gobierno Técnico de IA
+
+- **Objetivo**: asegurar gobernanza antes del despliegue.
+- **Acciones Hamilton**:
+  - Definir políticas para funciones declarativas: naming estándar, anotaciones de tipo, uso de `@tag`, `@check_output` y `@config.when`.
+  - Registrar decisiones en ADR cuando se introduzcan pipelines críticos (ver `docs/adr/`).
+  - Sincronizar ExecPlans con agentes SDLC (`SDLC_AGENTS_GUIDE.md`) para documentar qué modelo LLM respalda cada dataflow Hamilton.
+- **Artefactos**: sección adicional en `ESTRATEGIA_IA.md` (cuando aplique) apuntando a este documento.
+- **Métricas**: 100 % de funciones Hamilton con docstring y tipo; 100 % de pipelines con versionado Git.
+
+### Fase 3 — Fundamentos Técnicos y de Plataforma
+
+- **Objetivo**: preparar infraestructura reproducible.
+- **Acciones Hamilton**:
+  - Crear módulos Python bajo `scripts/coding/ai/` o `api/` siguiendo TDD; usar `pip install sf-hamilton` en entornos aislados.
+  - Implementar adaptadores Hamilton (`driver.Driver`) que permitan ejecutar pipelines en scripts CLI existentes.
+  - Integrar validaciones con `@check_output` y `pandera` (cuando esté habilitado) para cumplir requisitos de calidad de datos.
+- **Artefactos**: scripts de bootstrap (`scripts/ci/` o `scripts/validation/`) que llamen a pipelines Hamilton.
+- **Métricas**: suites `pytest` con coverage ≥ 80 % y pipelines reproducibles en ambientes locales (sin dependencia de servicios prohibidos).
+
+### Fase 4 — Despliegue Progresivo y Trabajo en Pequeños Lotes
+
+- **Objetivo**: liberar incrementos controlados.
+- **Acciones Hamilton**:
+  - Usar micro-orquestación para aislar funciones; habilitar `@parameterize` para iterar prompts.
+  - Ejecutar despliegues piloto en entornos controlados (ej. `scripts/run_all_tests.sh` + pipelines manuales) antes de ampliar cobertura.
+  - Documentar warm starts y reemplazos en ExecPlans y en la sección `[PLANIFICADO]` del índice.
+- **Artefactos**: registro de despliegues en `docs/qa/registros/` cuando se active Hamilton en producción.
+- **Métricas**: lead time <= baseline + 10 %, zero change failure rate atribuible a Hamilton.
+
+### Fase 5 — Medición, Validación y Mejora Continua
+
+- **Objetivo**: medir impacto y calidad.
+- **Acciones Hamilton**:
+  - Incluir pruebas unitarias e integración (LLM evals) que se puedan ejecutar en CI.
+  - Visualizar DAGs con `dr.visualize_execution(...)` y anexar capturas a documentación técnica.
+  - Integrar métricas de costo LLM y tiempos de ejecución en `logs_data/` para seguimiento de DORA metrics.
+- **Artefactos**: reportes periódicos en `logs_data/analysis/` o `docs/analisis/` con hallazgos.
+- **Métricas**: cobertura de pruebas Hamilton ≥ 80 %, reducción de tiempo de depuración (MTTR) medido vía `logs_data`.
+
+### Fase 6 — Escalamiento Técnico y Consolidación
+
+- **Objetivo**: institucionalizar Hamilton como parte del stack.
+- **Acciones Hamilton**:
+  - Migrar flujos manuales a pipelines Hamilton versionados; compartir componentes reutilizables en `hub.dagworks.io` cuando sean open-source friendly.
+  - Entrenar equipo usando esta guía + presentación original; registrar sesiones de conocimiento en `docs/ai/tareas/`.
+  - Evaluar integración con `DAGWorks` para observabilidad avanzada y versionamiento.
+- **Artefactos**: backlog de mejoras en `proyecto/TAREAS_ACTIVAS.md` y roadmap asociado.
+- **Métricas**: adopción Hamilton en ≥ 3 dominios (api, scripts, docs) y monitoreo en `AI_CAPABILITIES.md` actualizado.
+
+---
+
+## 3. Flujo operativo recomendado
+
+1. **Planificación**: crear o actualizar un ExecPlan (por ejemplo `docs/EXECPLAN_hamilton_framework_sdlc_integration.md`).
+2. **Diseño de dataflow**: definir funciones Hamilton con dependencias claras.
+3. **Implementación TDD**: escribir pruebas primero (`pytest`), luego código Hamilton.
+4. **Validación**: ejecutar `python3 -m pytest docs/qa/testing/test_documentation_alignment.py` y pruebas específicas del dominio.
+5. **Documentación**: actualizar `docs/index.md`, guías de agentes SDLC y registros de QA.
+6. **Revisión**: registrar métricas y decisiones en ExecPlans/ADRs.
+
+---
+
+## 4. Riesgos y mitigaciones
+
+| Riesgo | Mitigación |
+|--------|------------|
+| Falta de gobernanza sobre funciones generadas por IA | Requerir `@tag(owner=...)` y docstrings; auditar commits con metadata IA (Fase 2). |
+| Costos de LLM altos por evaluaciones | Segmentar pruebas (desarrollo vs pre-release) como sugiere la presentación, documentando costos en `AI_CAPABILITIES.md`. |
+| Integraciones mal instrumentadas | Mantener `scripts/run_all_tests.sh` actualizado y anexar nuevos comandos Hamilton. |
+| Debt técnico en prompts | Usar Hamilton para versionar prompts como funciones; cubrir con pruebas y registros en `docs/ai_capabilities/prompting/`. |
+
+---
+
+## 5. Validación y pruebas
+
+- **Obligatorio**: `python3 -m pytest docs/qa/testing/test_documentation_alignment.py` (garantiza existencia de esta guía y referenciación en el índice).
+- **Recomendado**: pruebas específicas por dominio (ej. `pytest scripts/coding/tests/` para pipelines en scripts) y visualización de DAGs.
+- **Documentación cruzada**: verificar que `docs/ai/SDLC_AGENTS_GUIDE.md` y `docs/index.md` enlacen a esta guía tras cada modificación.
+
+---
+
+## 6. Próximos pasos
+
+1. Incorporar ejemplos de código Hamilton en `scripts/coding/ai/` siguiendo TDD.
+2. Evaluar integración con `TASK-024-ai-telemetry-system.md` para recolectar métricas de ejecución.
+3. Registrar aprendizajes en `docs/qa/registros/` una vez ejecutados pilotos.
+
+---
+
+**Última actualización**: 2025-11-18  
+**Contacto**: Equipo de documentación SDLC (docs-agent)

docs/index.md

@@ -32,6 +32,7 @@ Este índice combina lo implementado con la visión futura del proyecto, clarame
   - Guía de uso por rol: [`GUIA_USO.md`](gobernanza/ci_cd/GUIA_USO.md)
   - Troubleshooting: [`TROUBLESHOOTING.md`](gobernanza/ci_cd/TROUBLESHOOTING.md)
   - Ejemplos: [`EJEMPLOS.md`](gobernanza/ci_cd/EJEMPLOS.md)
+- **Hamilton + 6 fases SDLC IA**: [`gobernanza/ai/HAMILTON_FRAMEWORK_INTEGRACION_SDLC.md`](gobernanza/ai/HAMILTON_FRAMEWORK_INTEGRACION_SDLC.md) - Guía para adaptar Hamilton al marco de gobierno IA.
 
 ### Arquitectura ([IMPLEMENTADO] Documentada, [PLANIFICADO] Evolución continua)
 - **ADRs**: [`adr/`](adr/) - 11+ Architecture Decision Records

docs/qa/testing/test_documentation_alignment.py

@@ -4,6 +4,7 @@
 
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
+PROJECT_ROOT = REPO_ROOT.parent
 
 
 def _read(path: Path) -> str:
@@ -129,6 +130,14 @@ def test_codex_mcp_multi_agent_guide_is_linked():
     assert "CodexMCPWorkflow Orchestrator" in agent_catalog
 
 
+def test_hamilton_framework_integration_doc_is_published():
+    guide_path = PROJECT_ROOT / "docs" / "gobernanza" / "ai" / "HAMILTON_FRAMEWORK_INTEGRACION_SDLC.md"
+    assert guide_path.exists(), "Debe existir la guía de integración Hamilton alineada a las 6 fases SDLC"
+
+    index_contents = _read(REPO_ROOT / "index.md")
+    assert "gobernanza/ai/HAMILTON_FRAMEWORK_INTEGRACION_SDLC.md" in index_contents
+
+
 def test_issue_templates_connect_execplans_and_agents():
     templates_dir = REPO_ROOT / ".github" / "ISSUE_TEMPLATE"
     assert templates_dir.exists(), "La carpeta .github/ISSUE_TEMPLATE debe existir"