Codebase Futuros²⁰³⁵ — Estado del arte

1.Resumen ejecutivo

Futuros pasó en seis meses de un blueprint en Markdown a una plataforma operacional con cuatro capas: (i) contenido editorial-grade en blueprint + research + pilots + stakeholders, (ii) un sistema de agentes Claude con 18 especialistas y 9 skills que produce contenido autónomo cada 12 minutos, (iii) un portal público en futuros.xyz con 179 páginas (atlas + ontología + grafo + dossiers país + dashboards), (iv) infraestructura de provenance (citations registry + validador CI) que captura errores antes de roadshow.

El estado actual permite empezar el roadshow del Compacto Soberano con Paraguay como Anchor 0 y abrir la ronda de funder Anillo 0 con Coefficient Giving. Lo que aún no permite es: deploy CI automático del portal, prevención automatizada de errores red-team-flagged que sobreviven entre ticks, ni publicación de la API REST que existe en api/main.py pero no está expuesta.

2.Métricas en una vista

Distribución de contenido por dominio

Agentes Markdown (.claude/agents/) vs. Specialists Python (agents/specialists/)

18 Markdown ↔ 19 Python. Los Markdown son los que se invocan vía Claude Code subagents (vivos en ticks); los Python son la versión library/API. La divergencia es real y systemic — flaggeada por meta-improver el 2026-05-03 como "md/py divergence is systemic risk".

3.Lo que tenemos

3.1 Blueprint — el documento vivo (15 capítulos + 3 pilares + changelog)

El blueprint es el centro editorial del proyecto. Todo cruza por aquí.

3.2 Pilotos (18 candidatos)

3.3 Sistema de agentes

Dos arquitecturas paralelas que cumplen funciones complementarias:

• Claude Code subagents (Markdown en .claude/agents/) — invocados por skills durante ticks. Inheritance del system prompt + tool restrictions per-agent. 18 agentes activos.
• Python specialists (clases en agents/specialists/) — library/API + base agent con prompt caching, retry, structured logging, observability. Soporte para FastAPI gateway. 19 specialists.

3.4 Skills (flows compuestos)

• futuros-tick — operador autónomo. Decide qué hacer cada 12 min basado en cadencia (ingest 24h / weekly 6d / audit 3d / drain queue / fallback country research).
• futuros-decision-brief — produce 5 deliverables (memo, deck, talking-points, elevator, objections) para un (target, ask) específico.
• futuros-design-pilot — pilot-designer + costing + risk + coherence → bankable pilot.
• futuros-audit-blueprint — coherence + kpi-auditor + risk sobre blueprint completo.
• futuros-review-country — researcher + stakeholder-mapper + risk país.
• futuros-ingest-feeds — RSS + arXiv + gov press releases.
• futuros-bilingual — ES + EN garantía.
• futuros-ab-prompt — A/B test prompt variants.

3.5 Tools (Python CLI)

• tools.cli — entry-point principal, requiere ANTHROPIC_API_KEY. validate / synthesize / publish.
• tools.citations — registry audit (audit/integrity/orphans/show). No requiere API key.
• tools.ingest + tools.ingest_sources — feed pull + embedding.
• tools.data_sources — World Bank / OECD / IDB / OWID adapters.
• tools.validate — coherence checks (frontmatter, orphan KPIs, country mismatch).
• tools.shadows + tools.triggers — counter-narrative shadows + decision-calendar triggers.
• tools.coalition + tools.alert_digest — coalition mapping + weekly alerts.
• tools.telemetry + tools.email_blast + tools.publish — observability + distribution.
• tools.memory_bootstrap + tools.seed_country_memory — agent memory init.
• tools.autonomy — daemon health + verdict.

3.6 Portal (Astro 4)

40 source pages, 179 built (incluye dynamic routes /o/{Type}/{id}).

3.7 Outputs (deliverables editorialmente firmados)

• Briefings privados (outputs/briefings/_private/): santiago-pena/ (5 deliverables decision brief), paraguay-anchor-0/track-II/ (5 memos confidenciales: Anthropic, GDM, Itamaraty, Cancillería PY, ANDE+MITIC), gustavo-petro/, alvaro-soto/, coefficient-giving/.
• Instruments: Compacto Soberano term sheet v0, RFI Paraguay-Itaipú 1 GW, MoU MATS template, MATS DD pack.
• Programs: Anillo 0 recruitment plan cohorte 1.
• Audits: 8 audits (coherence, blueprint, validator+red-team comprehensive).
• Coalitions + counter-narratives + alerts: shadow narratives + weekly alerts digest.

3.8 Truth infrastructure

• research/sources/_citations.yml — 17 citaciones activas + 4 deprecadas (con supersede).
• tools/citations.py — 4 subcomandos (audit, integrity, orphans, show), corre sin API key.
• /futuros/provenance — vista web pública del registry (gated por contraseña como el resto del portal).
• Dominios cubiertos: energy-, compute-, talent-, jurisdiction-, agi-.

3.9 State (memoria operacional)

• state/queue.md — append-only work queue (50+ items hoy).
• state/cycle-log.md — append-only ledger de cada tick (cadence engine).
• state/PLAN.md — 30-day priorities, regenerado mensualmente.
• state/decision-calendar.md — fechas críticas con shadows + triggers.
• state/feeds.yaml — fuentes de ingest activas.
• state/triggers.json + trigger-log.jsonl — automated event detection.
• state/twins/ — country digital-twins JSON.
• state/shadows/ — counter-narrative storage.
• state/improvement-log.md — meta-improver proposals + outcomes.
• state/notion-targets.md — allowlist de Notion DBs (control de write surface).
• state/recipients.md — email distribution list.
• state/telemetry.json — daemon health JSON.

3.10 Agent memory (persistente cross-conversation)

• agent-memory/countries/*.md — facts ledger por país (Brasil, México, Costa Rica, Argentina, Paraguay).
• agent-memory/individuals/*.md — signal log por decision-maker (Petro, Cartes, Sheinbaum, Lula, etc.).
• agent-memory/anchor-0-paraguay.md — strategic memo cross-tick.

4.Cómo funciona

4.1 El loop autónomo (24/7)

Routing rules (primera coincidencia gana)

1. Rule 0 — ingest: si último tick=ingest > 22h → pull feeds + embed.
2. Rule 1 — meta-improvement: si último tick=meta > 28d AND no PRs abiertos → propose 1-3 improvements as PRs.
3. Rule 2 — weekly: si último tick=weekly > 6d → ship rotating briefing.
4. Rule 3 — audit: si último tick=audit > 3d → run coherence-checker.
5. Rule 4 — drain queue: si state/queue.md tiene pending → process oldest.
6. Rule 5 — fallback: pick country/peer-initiative no investigado en 21d.

4.2 Tick anatomy (parallel)

1. Bootstrap: read cycle-log + queue + PLAN
2. Decide which rule applies → choose work units
3. Fan-out wave: up to 5 specialists in parallel (single message, multiple Agent calls)
4. Wait for wave to complete
5. Integrate outputs (file writes already happened by specialists)
6. Append cycle-log row with: started_at, finished_at, outputs, errors
7. git add + commit + push (if changes)
8. Exit cleanly

4.3 Quality gate (Builder/Validator split)

Cada output pasa por validator + red-team con contexto fresco. Validator verifica formal (frontmatter, schema, citations); red-team ataca el contenido (find bias, omissions, hallucinations). Findings se escriben como footers al archivo y se abren gh issues si CRÍTICO.

Patrón sistémico observado: errores red-team-flagged previos no propagan correcciones automáticas. X8 Cloud "50 MW" sobrevivió 3 ticks consecutivos hasta corrección manual q-31. Atacama "$2.5/MWh" propagó del g42-microsoft-compacto al blueprint cap. 12 antes de detección manual q-29.

4.4 Citations registry (CI gate)

Cada cifra cuantitativa en blueprint, pilots, briefings se registra en research/sources/_citations.yml con id, claim, value, source.url, verified_by. tools/citations.py corre 3 chequeos:

• integrity — registry health (missing fields, duplicate ids, broken supersede links).
• used-in-exists — file paths cited exist on disk.
• orphan-numerics — find unanchored claims in blueprint/* + pilots/candidates/*. Hoy reporta 546 orphans (legacy claims pre-registry).

4.5 Hard guardrails (.claude/settings.json)

• Edit(blueprint/01-vision.md) — denied. Vision es human-only.
• gh pr merge — denied. Auto-merge nunca permitido.
• git push --force, git reset --hard, rm -rf — denied.
• Edit(.env*), Read(.env*) — denied (env-guard).
• .claude/agents/{validator,meta-improver}.md — denied (auto-preservation: el agente no puede editarse a sí mismo).

4.6 Despliegue actual

El portal es estático (Astro). El usuario reportó que está live en futuros.xyz. La inferencia más probable: Cloudflare Pages con auto-deploy desde main (build command: cd portal && npm install && npm run build, output dir: portal/dist). El commit 043a830 "domain: cut over to futuros.xyz at root" sugiere que la cutover ya pasó. Sin embargo, no existe workflow de CI/CD en .github/workflows/ que lo documente — solo agents-ci.yml (Python tests) y lint-content.yml (markdown). El deploy es opaco.

5.Lo que falta

5.1 Crítico (bloquea o degrada el roadshow)

5.2 Importante (degrada calidad pero no bloquea)

5.3 Menor (mejora pero no urgente)

• Stakeholders por país (stakeholders/by-country/) tiene solo 1 archivo. Plan original: 1 archivo por país anchor.
• stakeholders/governance/ tiene solo 1 archivo. Falta estructuración Mesa Futuros / CELAC / IDB / CAF.
• Civil society stakeholders subdesarrollado (2 archivos).
• data/compatibility-matrix.json existe pero no se documenta su uso en portal.
• Decision-calendar (state/decision-calendar.md) tiene 1 row STATUS=needs-verify (CELAC PPT 2026-03-21).
• 5 gh issues abiertos sin owner explícito (#6 #7 #10 #16 #21).
• Output formats: HTML status pages existen (outputs/status.html, status-telemetry.html) pero no se enlazan desde portal nav.

6.Riesgos sistémicos

7.Qué hacer a continuación

Priorizado por desbloquear roadshow Q3 2026: lo que más afecta la firma del primer Compacto Soberano + el cierre de funder Anillo 0 va arriba.

P1 — Esta semana (bloquea roadshow Q3)

P2 — Próximas 2-4 semanas (desbloquea calidad y escala)

P3 — Q3 2026 (consolidación)

P4 — Q4 2026 / Q1 2027 (escala)

• Encryption-at-rest para outputs/briefings/_private/ (git-crypt o sops).
• Permission-tightening por skill: limitar gh issue create a meta-improver únicamente.
• Cobertura tests integración tick end-to-end.
• Pre-push hook: branch protection + validator+red-team antes de push.
• API REST con auth + audit log + rate limit.
• Ontology version v0.2 (con relations Anchor → Country → Compacto cumplidas).
• Onboarding doc para nuevos contributors humanos (cómo trabajar con el codebase + los agentes).

8.Referencias técnicas

8.1 Estructura de directorios

Futuros/
├── agents/                 # Python: orchestrator + 19 specialists + memory + tools + twins + base + safety + observability
├── agent-memory/           # Persistent memory cross-conversation: countries/, individuals/, anchor-0-paraguay.md
├── api/                    # FastAPI gateway (scaffolded; no deploy)
├── blueprint/              # 15 chapters + 3 pillars + _changelog
├── data/                   # cache/, memory/, compatibility-matrix.json
├── financial-model/        # 5 CSVs (embrión)
├── kpis/                   # framework + 3 dashboards
├── ops/                    # daemon supervisor + launchd plists + healthcheck
├── outputs/                # briefings (incl. _private/), audits, digests, instruments, programs, alerts, coalitions
├── pilots/                 # 18 candidates + templates
├── portal/                 # Astro 4 site (live at futuros.xyz)
│   └── src/
│       ├── data/, lib/, layouts/, components/, pages/  # 40 source pages
├── research/               # countries/, peer-initiatives/, sectors/, instruments/, sources/_citations.yml
├── stakeholders/           # individuals/, multilateral/, regional-bodies/, governments/, private-sector/, civil-society/, by-country/, sedes-anillo-0/, governance/
├── state/                  # queue, cycle-log, PLAN, decision-calendar, feeds, triggers, twins/, shadows/, recipients
├── tests/                  # 27 Python tests (smoke, safety, observability, quality_gate, country_twin, etc.)
├── tools/                  # 17 Python CLI tools (citations.py, cli.py, ingest.py, validate.py, etc.)
├── .claude/
│   ├── agents/             # 18 Markdown agents (Claude Code subagents)
│   ├── skills/             # 9 active skills (futuros-tick + 8 specialized)
│   └── settings.json       # Hard guardrails
├── .github/workflows/      # agents-ci.yml, lint-content.yml (no deploy workflow)
└── CLAUDE.md               # Project instructions

8.2 Comandos de operación

8.3 Archivos críticos a leer primero (onboarding humano)

1. CLAUDE.md — instrucciones del proyecto
2. blueprint/00-overview.md — tesis 1-página
3. blueprint/01-vision.md — visión 2035
4. blueprint/14-paraguay-anchor-0.md — depth-first decision
5. blueprint/_changelog.md — historia versionada
6. state/PLAN.md — 30-day priorities
7. state/queue.md — work queue activa
8. state/cycle-log.md — daemon ledger
9. .claude/skills/futuros-tick/SKILL.md — cómo opera el daemon
10. tools/citations.py — truth infrastructure

8.4 Versionado