docs(adr): agregar registros de decisiones de arquitectura ADR-0001, ADR-0002 y ADR-0003

Author: Medalcode

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **Architecture Decision Records (ADRs)**: Added `docs/adr/0001-agent-facade-pattern.md`, `0002-graphify-knowledge-graph.md`, and `0003-containerized-test-suite.md`.
 - **Automated Test Suite**: Integrated `tests/test_scripts.sh` providing Unit, Integration, Smoke, and Regression tests for shell scripts.
 - **GitHub Actions Integration**: Added QA test execution step to `.github/workflows/ci.yml`.
 - **Reproducible Docker Support**: Added lightweight `Dockerfile` and `.dockerignore` for containerized QA test execution.

docs/adr/0001-agent-facade-pattern.md

@@ -0,0 +1,23 @@
+# 1. Consolidación de Agentes mediante Facade Pattern (Medalcode-Agent)
+
+- **Estado:** Aprobado
+- **Fecha:** 2026-08-10
+- **Decisores:** Jonatthan Medalla (Software Architect / CTO)
+
+## Contexto y Problema
+
+Anteriormente, el repositorio contaba con múltiples especificaciones fragmentadas de sub-agentes en archivos Markdown independientes (`ReadmeArchitect.md`, `RoadmapMaster.md`, `AssetManager.md`, `SEOOptimizer.md`). Esta dispersión provocaba sobrecarga de tokens durante el contexto del LLM y dificultades en el mantenimiento de las instrucciones de desarrollo.
+
+## Decisión
+
+Adoptar el **Facade Pattern** consolidando todos los roles operativos en un único agente generalista stateful denominado **`Medalcode-Agent`**, definido centralizadamente en `agents.md`.
+
+## Consecuencias
+
+### Positivas
+- Reducción drástica del consumo de tokens en llamadas a la API de IA.
+- Fuente Única de Verdad (Single Source of Truth) para la marca personal y estrategia DevOps.
+- Simplificación del mantenimiento de prompts y playbooks.
+
+### Negativas
+- El archivo `agents.md` debe mantenerse altamente cohesionado para evitar convertirse en una especificación gigante desordenada.

docs/adr/0002-graphify-knowledge-graph.md

@@ -0,0 +1,23 @@
+# 2. Integración de Knowledge Graphs con Graphify
+
+- **Estado:** Aprobado
+- **Fecha:** 2026-08-10
+- **Decisores:** Jonatthan Medalla (Software Architect / CTO)
+
+## Contexto y Problema
+
+A medida que el ecosistema de repositorios crece (`mcp-servers`, `FinLogic`, `Nidus`, `GitSpy`), los agentes de Inteligencia Artificial necesitan comprender las relaciones entre componentes, lenguajes y arquitecturas sin consumir presupuesto excesivo leyendo cada archivo individual del proyecto.
+
+## Decisión
+
+Integrar la herramienta y skill **`graphify`** para extraer grafos de conocimiento estructurados (`graphify-out/`), generando nodos, aristas, comunidades y reportes de auditoría visuales (`graph.html` y `GRAPH_REPORT.md`).
+
+## Consecuencias
+
+### Positivas
+- Comprensión instantánea de la topología del codebase mediante algoritmos de detección de comunidades (Louvain/Leiden).
+- Visualizaciones interactivas en HTML para reclutadores e ingenieros.
+- Reducción del uso de tokens en consultas de arquitectura via BFS/DFS (`graphify query`).
+
+### Negativas
+- Los archivos en `graphify-out/` deben mantenerse sincronizados tras refactorizaciones mayores.

docs/adr/0003-containerized-test-suite.md

@@ -0,0 +1,21 @@
+# 3. Estrategia de Pruebas Automatizadas y Ejecución en Contenedores
+
+- **Estado:** Aprobado
+- **Fecha:** 2026-08-10
+- **Decisores:** Jonatthan Medalla (Software Architect / CTO)
+
+## Contexto y Problema
+
+Los scripts de automatización (`generate-assets.sh` y `git_sync.sh`) carecían de pruebas automatizadas y mostraban diferencias de comportamiento entre distintas versiones de Bash (Linux vs macOS Bash 3.2).
+
+## Decisión
+
+1. Desarrollar una suite de pruebas automatizadas en Shell POSIX portátil (`tests/test_scripts.sh`) que cubre Smoke, Unit, Integration y Regression tests.
+2. Contenedorizar el entorno de ejecución mediante un `Dockerfile` basado en `alpine:3.20` para garantizar 100% de reproducibilidad independientemente del sistema operativo del desarrollador.
+
+## Consecuencias
+
+### Positivas
+- Cero regresiones en la ejecución de scripts.
+- Verificación automática en la pipeline de CI de GitHub Actions.
+- Pruebas portables y reproducibles con un solo comando Docker.

graphify-out/GRAPH_REPORT.md

@@ -1,7 +1,7 @@
 # Graph Report - .  (2026-08-10)
 
 ## Corpus Check
-- Corpus is ~4,122 words - fits in a single context window. You may not need a graph.
+- Corpus is ~4,557 words - fits in a single context window. You may not need a graph.
 
 ## Summary
 - 18 nodes · 25 edges · 4 communities (3 shown, 1 thin omitted)

graphify-out/cache/stat-index.json

@@ -1 +1 @@
-{".github/workflows/agent-scheduler.yml":{"size":1498,"mtime_ns":1786334202673413400,"word_count":158},".github/workflows/ci.yml":{"size":1064,"mtime_ns":1786334497578056500,"word_count":113},"README.md":{"size":12087,"mtime_ns":1786334571450624700,"word_count":1338},"agents.md":{"size":1654,"mtime_ns":1786333548013893600,"word_count":215},"generate-assets.sh":{"size":9563,"mtime_ns":1786334292027104500,"word_count":955,"hashes":{"generate-assets.sh":"51c24c386156dd6531110c79638c508470e40e5fd51b9ba0041ce52a58e17229"}},"git_sync.sh":{"size":3479,"mtime_ns":1786334303373471400,"word_count":408,"hashes":{"git_sync.sh":"a5668b263b3e5585473fc619761ac9fddd9d52a555d1a8991baa6147ff1beb7c"}},"skills.md":{"size":3014,"mtime_ns":1786333548014892600,"word_count":376},"tests/test_scripts.sh":{"size":3187,"mtime_ns":1786334487398399400,"word_count":325,"hashes":{"tests/test_scripts.sh":"0114c7c1c596c30929f0854d52fd5982009f19c8173416d5ac8b2d54babd4424"}},"CHANGELOG.md":{"size":2017,"mtime_ns":1786334554828566600,"word_count":234}}
+{".github/workflows/agent-scheduler.yml":{"size":1498,"mtime_ns":1786334202673413400,"word_count":158},".github/workflows/ci.yml":{"size":1064,"mtime_ns":1786334497578056500,"word_count":113},"README.md":{"size":12087,"mtime_ns":1786334571450624700,"word_count":1338},"agents.md":{"size":1654,"mtime_ns":1786333548013893600,"word_count":215},"generate-assets.sh":{"size":9563,"mtime_ns":1786334292027104500,"word_count":955,"hashes":{"generate-assets.sh":"51c24c386156dd6531110c79638c508470e40e5fd51b9ba0041ce52a58e17229"}},"git_sync.sh":{"size":3479,"mtime_ns":1786334303373471400,"word_count":408,"hashes":{"git_sync.sh":"a5668b263b3e5585473fc619761ac9fddd9d52a555d1a8991baa6147ff1beb7c"}},"skills.md":{"size":3014,"mtime_ns":1786333548014892600,"word_count":376},"tests/test_scripts.sh":{"size":3187,"mtime_ns":1786334487398399400,"word_count":325,"hashes":{"tests/test_scripts.sh":"0114c7c1c596c30929f0854d52fd5982009f19c8173416d5ac8b2d54babd4424"}},"CHANGELOG.md":{"size":2184,"mtime_ns":1786335105923330000,"word_count":244},"docs/adr/0001-agent-facade-pattern.md":{"size":1181,"mtime_ns":1786335094200384500,"word_count":149},"docs/adr/0002-graphify-knowledge-graph.md":{"size":1155,"mtime_ns":1786335098317947000,"word_count":144},"docs/adr/0003-containerized-test-suite.md":{"size":990,"mtime_ns":1786335102178251900,"word_count":132}}

graphify-out/graph.json

@@ -544,5 +544,5 @@
     }
   ],
   "hyperedges": [],
-  "built_at_commit": "717dabc323463927c58bec50f066e3c6c8f7bedb"
+  "built_at_commit": "068dc5ef4fb192c9b92dbc7b54393fd811292740"
 }