docs: README, ARCHITECTURE, roadmap futuro y manual de QA del dashboard

- README.md: pitch, arquitectura, quickstart, demo guiada en 3 pasos, tabla de
  capacidades, estructura del repo, comandos de tests.
- ARCHITECTURE.md: patrones (Strategy, config-over-code, fail-closed,
  trazabilidad), tabla de persistencia, patrón HITL, observabilidad, errores.
- docs/futuro.md: roadmap post-MVP.
- docs/manual_qa.md: checklist del smoke manual del dashboard (5 páginas + PII +
  persistencia).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

ARCHITECTURE.md

@@ -0,0 +1,71 @@
+# AgentForge — Arquitectura técnica
+
+> Documento "vivo" con las decisiones técnicas. El spec original está en
+> [`docs/superpowers/specs/2026-05-09-agentforge-design.md`](docs/superpowers/specs/2026-05-09-agentforge-design.md).
+
+## Visión general
+
+Two-tier:
+- `agentforge-core` — FastAPI 8000. Dominio de gobierno, runtime LangGraph,
+  guardrails y persistencia.
+- `agentforge-dashboard` — Streamlit 8501. Cliente HTTP del core.
+
+## Diagrama
+
+```
+┌─────────────────────┐  HTTP/JSON  ┌─────────────────────┐
+│ Dashboard (Stream.) │ ───────────► │ Core (FastAPI)      │
+└─────────────────────┘              └─────────┬───────────┘
+                                               │
+            ┌─────────────────────────┬────────┴──────┬────────────┐
+            ▼                         ▼               ▼            ▼
+       LLM layer              Guardrails layer   LangGraph     State
+   (Strategy pattern)         (Strategy pattern)  Runtime      JSON+SQL+JSONL
+```
+
+## Patrones aplicados
+
+- **Strategy / Plugin**: `LLMProvider`, `GuardrailEngine`, `AgentRegistry`,
+  `PolicyStore` son `Protocol`s con varias implementaciones intercambiables
+  vía factory que lee `Settings`.
+- **Configuration over code**: agentes y políticas como YAML versionados;
+  cambios sin redeploy.
+- **Fail-closed por defecto**: errores en validadores cuentan como bloqueo.
+- **Trazabilidad obligatoria**: `trace_id` UUID propagado por
+  middleware → structlog → API → JSONL.
+
+## Persistencia
+
+| Capa | Tecnología | Por qué |
+|---|---|---|
+| Agent Registry | JSON + YAML | Humano lo escribe (YAML); máquina lo cataloga (index.yaml). |
+| Versionado | YAML por versión + index.yaml | Diff legible; hash SHA-256 normalizado. |
+| Logs de violaciones | JSONL append-only | Inmutable, auditable, fácil de shipear. |
+| Logs de ejecuciones | JSONL append-only | Idem. |
+| Checkpoints LangGraph | SQLite | Tool right; persistencia entre restarts (HITL). |
+
+## HITL — Patrón
+
+Se usa la API dinámica `interrupt(payload)` de LangGraph ≥0.2 dentro del
+nodo `approve_gate`. Sólo pausa cuando hay acciones de alto riesgo
+(`risk_score >= threshold` o `requires_approval=True`). El cliente envía
+`Command(resume={"approved_action_ids": [...]})` vía
+`POST /executions/{trace_id}/approve`.
+
+## Observabilidad
+
+- `structlog` con renderer JSON.
+- Middleware FastAPI inyecta `X-Trace-Id` y bind-ea contexto.
+- Cada nodo del grafo añade un step a `decision_path` con `duration_ms`.
+
+## Errores
+
+- Azure OpenAI / OpenAI: retry exponencial 1s/2s/4s, fallback opcional, luego
+  `status=failed`.
+- Validador: `fail_closed` por defecto.
+- Schema mismatch en LLM output: 1 retry, luego `failed`.
+- Checkpoint corrupto: 500 explícito (sin auto-recovery).
+
+## Decisiones pospuestas
+
+Ver [`docs/futuro.md`](docs/futuro.md).

README.md

@@ -0,0 +1,101 @@
+# 🛡️ AgentForge
+
+Plataforma profesional de **gobernanza de agentes IA**: catalogación, versionado
+de prompts y políticas, guardrails runtime, ejecución stateful con
+Human-in-the-Loop, observabilidad y trazabilidad end-to-end.
+
+## ¿Por qué?
+
+Poner agentes IA en producción sin una capa de gobierno produce sistemas
+opacos: prompts que cambian sin historial, validaciones inconsistentes,
+acciones de alto impacto sin supervisión, sin auditoría de decisiones.
+AgentForge aporta el plano de control mínimo que un equipo de plataforma
+necesita antes de operar agentes con impacto real.
+
+## Arquitectura
+
+```
+┌───────────────────────── docker-compose ──────────────────────────┐
+│                                                                    │
+│  ┌─────────────────────┐     HTTP/JSON     ┌────────────────────┐ │
+│  │ agentforge-dashboard│ ────────────────► │ agentforge-core    │ │
+│  │ Streamlit  :8501    │ ◄──────────────── │ FastAPI    :8000   │ │
+│  └─────────────────────┘                   └────────────────────┘ │
+│                                                                    │
+│   Strategy pattern (Protocol) para LLMProvider, GuardrailEngine,  │
+│   AgentRegistry. Persistencia mixta: YAML (definiciones), JSON    │
+│   (registry), JSONL (logs append-only), SQLite (checkpoints).     │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+Detalles completos en [`ARCHITECTURE.md`](ARCHITECTURE.md).
+
+## Quickstart
+
+```bash
+cp .env.example .env
+docker compose up
+```
+
+Abre [http://localhost:8501](http://localhost:8501).
+
+Funciona out-of-the-box (`LLM_PROVIDER=mock`, sin API keys). Si quieres usar
+Azure OpenAI real, edita `.env`.
+
+## Demo guiada (3 pasos)
+
+1. **Registro** → ver `incident_analyzer` y comparar `v1` vs `v2`.
+2. **Ejecutar** → seleccionar el escenario `01_sip_registration_drop` y
+   pulsar *Invocar*. Verás el grafo recorrer validate_input → llm_reason
+   → validate_output → propose_actions → approve_gate y pausarse en HITL.
+3. **Aprobaciones** → revisar las acciones propuestas (con risk_score y
+   rollback_plan), aprobar las seguras y comprobar que la ejecución
+   completa.
+
+## Capacidades implementadas
+
+| Feature | Ubicación |
+|---|---|
+| Agent Registry | `core/src/agentforge_core/registry/repository.py` |
+| Versionado tipo Git | `agents/<name>/versions/` + `registry/versioning.py` |
+| Guardrails runtime | `core/src/agentforge_core/guardrails/` |
+| LangGraph stateful + checkpointing | `core/src/agentforge_core/runtime/` |
+| Human-in-the-Loop | nodo `approve_gate` + endpoints `/approve` y `/reject` |
+| Observabilidad | `observability/logging.py` (structlog + trace_id) |
+| LLM provider abstraction | `core/src/agentforge_core/llm/` |
+| Política versionada | `policies/default/versions/v1.yaml` |
+
+## Variables de entorno
+
+Ver [`.env.example`](.env.example).
+
+## Roadmap
+
+Ver [`docs/futuro.md`](docs/futuro.md).
+
+## Estructura del repositorio
+
+```
+agentforge/
+├── core/                 servicio FastAPI
+├── dashboard/            servicio Streamlit
+├── agents/               definiciones declarativas (YAML)
+├── policies/             políticas de guardrails
+├── data/                 estado runtime (gitignored)
+├── tests/                pytest unit + integration
+└── docs/                 documentación adicional
+```
+
+## Tests
+
+```bash
+make install
+make test         # solo unit
+make test-all     # unit + integration
+make lint         # ruff + mypy
+make smoke        # docker-compose + curl health
+```
+
+## Licencia
+
+MIT (a confirmar).

docs/futuro.md

@@ -0,0 +1,15 @@
+# Roadmap (post-MVP)
+
+- **NeMo Guardrails full**: configuración Colang con KB embedding + dialog rails.
+- **Autenticación**: OAuth2/OIDC con MSAL para entornos Azure AD.
+- **OpenTelemetry**: spans por nodo del grafo, métricas de violaciones por validador.
+- **Multi-tenant**: `tenant_id` aislado por registry, política y datos.
+- **Evaluadores LLM-as-judge**: regression suite que ejecuta cada agente
+  sobre escenarios canónicos y mide deriva.
+- **UI de aprobación con SLA**: cola Kanban, reasignación entre operadores,
+  alertas cuando un HITL rebasa SLA.
+- **Persistencia migrable a Postgres + pgvector**: requerido para alta
+  disponibilidad multi-instance.
+- **Esquema de prompts mejorado**: variables tipadas en system_prompt
+  (Jinja-like), valores por entorno.
+- **Promoción explícita draft → active** vía PR/aprobación.

docs/manual_qa.md

@@ -0,0 +1,58 @@
+# Smoke manual del dashboard
+
+> Esta lista cubre los flujos no automatizados (Streamlit). Ejecutar tras
+> cambios visuales o estructurales del dashboard.
+
+## Setup
+
+```bash
+cp .env.example .env
+docker compose up -d
+sleep 15
+```
+
+Abrir [http://localhost:8501](http://localhost:8501).
+
+## 1) Registro
+
+- [ ] Aparece `incident_analyzer` en el desplegable.
+- [ ] Detalle muestra version, owner, propósito, guardrails, system_prompt.
+- [ ] Tabla de versiones lista `v1` y `v2`.
+- [ ] Diff `v1 → v2` muestra cambios coloreados.
+
+## 2) Ejecutar
+
+- [ ] Botones de escenarios cargan texto en el textarea.
+- [ ] Invocar `02_mos_degradation_pool_sbc` → status=`completed`, sin HITL,
+      decision_path con 6 steps.
+- [ ] Invocar `01_sip_registration_drop` → status=`awaiting_approval`,
+      banner amarillo redirige a Aprobaciones.
+
+## 3) Aprobaciones
+
+- [ ] La ejecución pendiente aparece en el desplegable.
+- [ ] Cada acción muestra risk_score con color, target y rollback_plan.
+- [ ] Aprobar acciones seleccionadas → status=`completed`.
+- [ ] Rechazo con razón → status=`failed`, error=`rejected_by_human`.
+
+## 4) Historial
+
+- [ ] Tab "Ejecuciones" lista todas las ejecuciones con summary.
+- [ ] Detalle muestra trace + violations.
+- [ ] Tab "Violaciones" filtrable por severity.
+
+## 5) Politicas
+
+- [ ] `default` aparece con sus validadores de input/output.
+- [ ] Cada validador expandible con su config.
+
+## Bloqueo por PII (input)
+
+- [ ] Pegar `El cliente con NIF 12345678Z reporta caída`.
+- [ ] Invocar → status=`blocked_by_guardrail`, violación `DetectPII`.
+
+## Persistencia
+
+- [ ] `docker compose down && docker compose up` → ejecuciones previas
+      siguen accesibles vía Historial; aprobaciones pendientes siguen
+      pendientes.