TÁNDEM

Refinamiento cruzado entre dos LLM — Claude Code CLI × Codex CLI — que trabajan en paralelo sobre copias aisladas del mismo material, se critican mutuamente con evidencia re-ejecutada, absorben cada uno lo mejor del otro y solo convergen cuando se cumple un predicado de excelencia computable (gates verdes + doble APPROVE + puntuación mínima).

Este repositorio implementa la arquitectura descrita en tandemarquitectura.md (proyecto LLM COLLAB). Las referencias §N de los comentarios del código apuntan a las secciones de ese documento.

---

1. Estado actual: esqueleto + base técnica

Módulo	Fichero(s)	Estado
Protocolo de mensajes (§5)	src/protocol/schemas.ts	✅ Completo: schemas zod de Finding, Critique, WorkResult, TaskSpec, EvidenceReport, TandemConfig, WorkPackage, ReviseInput, Rebuttal + parseAgentJson (extracción y auto-reparación de JSON)
Plantillas de prompt (§10)	src/protocol/prompts/*.md + prompts.ts	✅ Las 6 plantillas (spec-sync, produce, critique, revise, merge, audit) + motor de renderizado con bloques condicionales
Máquina de estados (§3)	src/orchestrator/state-machine.ts	✅ Fases, transiciones legales validadas, estado del run, helpers de ronda
Controlador de convergencia (§6)	src/orchestrator/convergence.ts	✅ checkConvergence + isStagnant con lógica real y tests (incluye anti-adulación)
Ejecución de ronda (§3–§4)	src/orchestrator/round.ts	✅ Generalizada PRODUCE|REVISE ∥ → snapshots git → gates → crítica cruzada ∥ → adjudicación; cancelación del hermano si un agente cae; test de integración sobre repo git real
Bucle completo (Fase 2)	src/orchestrator/loop.ts	✅ SPEC_SYNC negociado (proponer→fusionar→votar, 2 intentos→ESCALATE) · bucle multironda con CHECK · REBUTTAL con contra-evidencia re-ejecutada · MERGE con integrador rotatorio · FINAL_AUDIT por el que NO integró · una corrección acotada · DELIVER copy-out · kill-switch cooperativo
Adaptadores (§7)	src/adapters/	✅ produce()/critique()/revise() + ask() genérico validado en ambos. Claude: stdin + auto-reparación con --resume + sesión encadenada entre rondas. Codex: exec - + --output-schema. Modelos configurables por agente
Workspace Manager (§9)	src/workspace/	✅ copy-in + repo interno + worktrees (A/B/merge) + install por worktree + deliver copy-out (sin .git ni node_modules)
Evidence Runner (§8)	src/evidence/	✅ runGates + adjudicación de findings + adjudicación de contra-evidencia (REBUTTAL, semántica inversa); rúbrica/links (modo docs) — Fase 3
Informes	src/orchestrator/report.ts	✅ Por ronda (comparativo) + final multironda: tabla de rondas, fusión y auditoría, backlog no bloqueante de minors, mapa de discrepancias si ESCALATE
Persistencia (§9)	src/store/	✅ SQLite (runs/rounds/messages + history para resume) + transcript JSONL append-only, alimentados en vivo
CLI (§12)	src/index.ts	✅ COMPLETO: run (bucle entero) · status · report · stop (sentinela) · resume (frontera de ronda o directo a MERGE) · doctor
Cabina MCP — Variante B (§14)	src/mcp/server.ts + mcp/server.ts	✅ Servidor MCP stdio para Claude Desktop: 7 tools (tandem_start/status/report/stop/resume/list/doctor), runs en segundo plano, testeado con cliente MCP real. Setup: mcp/README.md
Modo docs funcional	src/evidence/validators/docs-structure.ts	✅ Gate mecánico de memorias vía tandem.docs.json: cobertura LITERAL del baremo, secciones en espejo, anticontaminación (términos vetados), límites de extensión, cero «rojos», ficheros exigidos; + links locales
Eje de entornos	src/workspace/agent-env.ts	✅ agentEnv: personal (cada cuenta con su arsenal — duelo de EQUIPOS; cada modelo interpreta sus skills a su manera, declarándolo en NOTES) | clean (solo auth — duelo de MODELOS); manifiesto arsenal.json por run; sharedTools MCP idénticas a ambos CLIs (metro común)
Verticales	src/verticals.ts + verticals/	✅ Arquitecturas especializadas como DATOS (config + normas + plantillas), kernel ciego al dominio. Primero: licitaciones (método NextHorizont: espejo del baremo, anclaje literal, anticontaminación) — --vertical licitaciones
Ejecución compartida	src/execute.ts	✅ executeLoop + buildResumeState comunes a CLI y MCP (logger inyectable; store SIEMPRE por import dinámico)
Dashboard / MCP (§12, §14)	dashboard/, mcp/	🔲 Placeholders con diseño — Fase 3

Leyenda: ✅ implementado y testeado · 🟡 parcial (lo indicado pendiente) · 🔲 diseñado, sin código.

---

2. Requisitos

1. Node ≥ 20 (probado con Node 22).
2. pnpm (corepack enable o https://pnpm.io/installation).
3. git en el PATH (los worktrees son el mecanismo de aislamiento).
4. Claude Code CLI con login de tu suscripción (claude en el PATH).
5. Codex CLI con codex login de tu suscripción ChatGPT.

Los CLIs solo hacen falta para ejecutar runs reales; para desarrollar y testear el orquestador no se necesitan.

---

3. Puesta en marcha, paso a paso

# 1) Entra en la carpeta del proyecto
cd tandem

# 2) Instala dependencias (siempre pnpm, nunca npm)
pnpm install

# 3) Comprueba que el esqueleto compila con TypeScript estricto
pnpm typecheck

# 4) Ejecuta la batería de tests (convergencia, máquina de estados, protocolo)
pnpm test

# 5) Diagnóstico del entorno: qué CLIs tienes y cuáles faltan
pnpm dev doctor

# 6) DUELO COMPLETO (Fase 2): bucle entero hasta la entrega auditada
pnpm dev run --dir ..\mi-carpeta --task "Tarea concreta y verificable"
#
#    Fases (cada ronda tarda MINUTOS — §16.1):
#      SPEC_SYNC (pactan la spec) → PRODUCE ∥ → gates → crítica cruzada
#      → adjudicación → REBUTTAL (contra-evidencia) → CHECK
#      → [REVISE con polinización cruzada → …]* hasta MERGE o ESCALATE
#      → fusión dirigida (integrador rotatorio) → FINAL_AUDIT (el otro)
#      → entrega en runs/<id>/final (o --out <carpeta>)
#
#    Flags útiles:
#      --blind            crítica sin autoría (Solución 1/2)
#      --no-spec-sync     usar la tarea literal como spec
#      --no-rebuttal      sin fase de contra-evidencia
#      --integrator claude|codex|auto
#      --model-claude X · --model-codex Y
#      --max-rounds 4 · --threshold 90 · --out D:\resultado

# 7) Control del run en vuelo (desde otra terminal)
pnpm dev status <run-id>     # rondas, gates, scores, decisiones
pnpm dev stop <run-id>       # kill-switch: para en la próxima frontera de fase
pnpm dev resume <run-id>     # reanuda desde la última ronda persistida
pnpm dev report <run-id>     # imprime el informe final

Notas: ambos CLIs deben tener login hecho (claude y codex login); tu carpeta original nunca se toca (copy-in → todo pasa en runs/<id>/, y la entrega es copy-out); resume re-produce la ronda que estaba en vuelo sobre los worktrees existentes.

---

4. Estructura del repositorio (§11)

tandem/
├── package.json                  # pnpm · Node ≥ 20 · ESM · TypeScript estricto (sin `any`)
├── tsconfig.json
├── src/
│   ├── index.ts                  # CLI (commander): run · status · report · resume · doctor · stop
│   ├── orchestrator/
│   │   ├── state-machine.ts      # fases y transiciones (§3)
│   │   ├── round.ts              # ejecución de una ronda (§3–§4)  [Fase 1]
│   │   └── convergence.ts        # checkConvergence + isStagnant (§6)
│   ├── adapters/
│   │   ├── agent-adapter.ts      # interfaz común + AgentContext (§7)
│   │   ├── claude-code.ts        # claude -p / --resume (headless)
│   │   └── codex.ts              # codex exec / resume / --output-schema (headless)
│   ├── protocol/
│   │   ├── schemas.ts            # zod: TODOS los mensajes agente↔orquestador (§5)
│   │   ├── prompts.ts            # carga y renderizado de plantillas
│   │   └── prompts/              # spec-sync · produce · critique · revise · merge · audit (§10)
│   ├── workspace/
│   │   ├── git.ts                # helpers git (repo interno del run)
│   │   ├── worktrees.ts          # ws-A / ws-B / ws-merge (§9)
│   │   ├── diff.ts               # snapshots etiquetados r<N>-A/B y diffs
│   │   └── merge.ts              # entrega fast-forward / copy-out  [Fase 2]
│   ├── evidence/
│   │   ├── runner.ts             # runGates + replayEvidence (el árbitro no-LLM, §8)
│   │   └── validators/           # typecheck · lint · tests · build · rubric · links
│   └── store/
│       ├── db.ts                 # SQLite: runs · rounds · messages (coste/latencia)
│       └── transcript.ts         # JSONL append-only auditable
├── test/                         # vitest: convergencia · máquina de estados · protocolo
├── dashboard/                    # Fase 3 (Next.js, Server Components sobre la SQLite)
└── mcp/                          # Fase 3 (variante B: cabina de mando en Claude Desktop)

---

5. Decisiones técnicas ya cerradas en el esqueleto

1. ESM + NodeNext: imports con extensión .js obligatoria. TypeScript en modo máxima estrictez (strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes); el tipo any está prohibido.
2. El APPROVE nunca contradice la evidencia: implementado en convergence.ts (no confiado al modelo) y testeado en test/convergence.test.ts (caso "ANTI-ADULACIÓN").
3. Sin checks aplicables no hay pase gratis: runGates devuelve pass=false si ningún validador aplica — obliga a configurar gates o rúbrica antes de que nada pueda aprobarse.
4. Un finding sin evidencia no existe: FindingSchema exige evidence no vacía; la re-ejecución (replayEvidence) la adjudica en Fase 1.
5. Codex valida en origen, Claude en destino: Codex usa --output-schema (JSON conforme garantizado); para Claude, parseAgentJson + bucle de auto-reparación sobre la misma sesión (máx. 2 intentos).
6. Identidad git local por run: el repo interno usa tandem-orchestrator <tandem@localhost> — no toca tu configuración global.
7. Línea de comandos fija + datos por stdin (src/util/exec.ts): los CLIs se invocan con shell: true (imprescindible para los shims .cmd de Windows) pero el prompt NUNCA se interpola en la línea de comandos — viaja por stdin (claude -p y codex exec -). Cero problemas de escapado en cmd.exe y sh.
8. Heurística de adjudicación documentada (src/evidence/runner.ts): buscadores (grep/rg) reproducen con exit 0; comandos normales con exit ≠ 0 o si la salida contiene la expectativa declarada tras →; citas si el fichero:línea existe. Los disputed no cuentan (§5) pero quedan en el informe y el transcript.
9. La identidad de las críticas la normaliza el orquestador: author/target/round se sobreescriben tras el parseo — un agente no puede atribuirse la autoría que quiera (testeado).
10. REBUTTAL con semántica inversa: la contra-evidencia del autor gana si su comando TIENE ÉXITO (exit 0 o expectativa presente) — al revés que un finding, donde el fallo demuestra el defecto. Contra-evidencia no ejecutable = finding mantenido (se exige comando, no prosa).
11. SPEC_SYNC en tres pasos deterministas: proponer ∥ → fusiona uno → vota el otro; si rechaza, fusiona el que rechazó (con sus objeciones sobre la mesa) y vota el primero; segundo rechazo → ESCALATE spec_conflict. Barato de escalar en ronda 0, caro en ronda 4 (§3).
12. Kill-switch cooperativo: tandem stop crea el sentinela STOP; el bucle lo consulta entre fases (los CLIs en vuelo no se matan a mitad). resume retoma en frontera de ronda re-produciendo la ronda en vuelo sobre los worktrees existentes.
13. Cancelación del hermano: si un agente cae en una fase paralela, el otro se aborta vía AbortSignal → no quedan procesos huérfanos consumiendo cuota.
14. Normas del duelo (Karpathy Guidelines adaptadas): los cuatro principios de multica-ai/andrej-karpathy-skills (MIT) — pensar antes de programar, simplicidad primero, cambios quirúrgicos, ejecución guiada por objetivos — se inyectan automáticamente en los prompts en DOS caras: norms-build.md para quien produce/revisa/fusiona y norms-review.md para quien critica/audita (los incumplimientos objetivos son material legítimo de finding, sin relajar la evidencia obligatoria ni habilitar bloqueos por estilo). Adaptación clave: el "pregunta si dudas" headless se canaliza a supuestos declarados en NOTES.md y ambigüedades resueltas en SPEC_SYNC. Se desactivan pasando NORMS: null a buildPrompt (o editando los .md).

---

6. Roadmap — qué implementar y en qué orden

Fase 1 — MVP (una ronda demostrable) — ✅ COMPLETADA (y validada con un duelo real en producción).

Fase 2 — Bucle completo — ✅ COMPLETADA (validada en producción: run cfa59ae1, fusión de codex auditada por claude y entregada).

Variante B — Cabina en Claude Desktop — ✅ COMPLETADA: servidor MCP local con runs en segundo plano (ver mcp/README.md).

Fase 3 — Confort (pendiente): dashboard Next.js, modo docs (rúbricas + links), contenedores, deliver fast-forward en modo-rama, sesión persistente de Codex (exec resume + eventos --json), tabla de rondas del informe reconstruida desde la BD en runs reanudados.

Fase 3 — Confort: dashboard Next.js, servidor MCP (variante B), modo docs (rúbricas + links), --blind operativo, presupuestos finos, contenedores.

---

7. Solución de problemas (Windows)

better-sqlite3 falla al instalar con «"node-gyp" no se reconoce…». El proyecto fija better-sqlite3@^12 a propósito: la v12 instala con prebuild-install || node-gyp rebuild, es decir, descarga un binario ya compilado para tu plataforma (hay binarios win32-x64 para Node 22 — ABI 127 — y Node 24 — ABI 137) y solo compila como último recurso. La v13 eliminó los binarios precompilados y SIEMPRE compila desde código, lo que en Windows exige Python + Visual Studio Build Tools. Si con la v12 sigue intentando compilar, tu versión de Node no tiene binario publicado: comprueba node -v y usa Node 22 o 24 LTS.

doctor decía que un CLI no estaba, pero sí está. En Windows, pnpm/claude/codex son shims .cmd, y Node (tras el parche de seguridad CVE-2024-27980) se niega a spawnearlos sin shell (error EINVAL). El doctor ya los invoca con shell: true. Verifica en una terminal nueva que claude --version y codex --version responden.

codex aborta con «Not inside a trusted directory». Es su puerta de confianza: en modo interactivo pregunta si confías en la carpeta; en headless no puede y aborta. TANDEM ya invoca codex exec con --skip-git-repo-check (seguro: el cwd es siempre el worktree git del run). Si lo ves, tu copia del adaptador es antigua.

codex escupe errores «failed to load skill … missing YAML frontmatter». Son NO fatales: codex rechaza skills personales de ~/.agents/skills/ cuyo SKILL.md no empieza por ---, y continúa. Puedes ignorarlos o poner esas skills en cuarentena para limpiar el ruido (muévelas a otra carpeta y reviértelo cuando quieras).

Runs reales en Windows. Los CLIs se lanzan con línea de comandos fija + prompt por stdin (ver decisión 7), que funciona en Windows nativo. Si tu instalación de codex no soportara --sandbox workspace-write en Windows, la alternativa es ejecutar los runs bajo WSL2.

8. Seguridad (§13) — ya reflejada en el esqueleto

• Claude: --permission-mode acceptEdits + lista blanca CLAUDE_ALLOWED_TOOLS (nunca bypassPermissions fuera de contenedor).
• Codex: --sandbox workspace-write (escritura limitada al worktree).
• runs/ está en .gitignore (contiene worktrees y transcripts); .env fuera del árbol que ven los agentes.
• Timeouts por fase (phaseTimeoutMs) y presupuesto por run (budgetMs) en la config.