dream-cycle

Dream Cycle v0: sintetiza un corpus de evaluación post-cutoff desde cualquier repo de GitHub (repo2rlenv pr_diff), lo calibra con agentes oracle/nop vía harbor, lo gatea con falsificación y corre un radar de capacidad reactivo.

El radar propone; el humano decide.

  1. SINTETIZAR   repo2rlenv generate pr_diff (PRs post-cutoff, sin LLM)
        │
  2. ENDURECER    Dockerfiles (repos privados: set-url después del reset)
        │
  3. CALIBRAR     harbor oracle (gold ⇒ ~1.0) + nop (nulo ⇒ 0.0)
        │
  4. CURAR        tareas inevaluables (oracle < 0.999) → exclusiones DECLARADAS
        │
  5. GATE         oracle debe PASAR · nop debe FALLAR (falsificación)
        │
  6. RADAR        compara result.json entre runs → gaps con borrador de issue

Alcance: dónde encaja en el loop de investigación

Este paquete cubre solo la etapa 0 del loop de auto-mejora (BLUEPRINT-008): decidir QUÉ se mejora, con corpus gateado y radar de gaps. Las etapas siguientes del ciclo viven fuera del paquete y no son requisitos para usarlo:

| Etapa del ciclo | Pieza | Relación con este paquete | |---|---|---| | 0 — sintetizar · gatear · radar | este paquete | dream-cycle run / radar | | 2A+3A — auto-mejora del harness | SIA (ADR-010) | consume las tareas que este paquete sintetiza, vía el adapter repo2rlenv-to-sia.py | | memoria cross-run | bridge Harbor→ReasoningBank (ADR-009) | destila las trayectorias de los jobs harbor que este paquete produce |

El Dream Cycle decide qué se mejora; SIA reescribe; ReasoningBank recuerda. SIA no detecta gaps — necesita que le den la tarea (ADR-010 §Deliberately NOT) — por eso el radar de este paquete es quien alimenta esa cadena.

Instalación

npm install -g dream-cycle    # o sin instalar:
npx dream-cycle doctor

Requisitos externos

El paquete no trae dependencias npm, pero el subcomando run orquesta cuatro herramientas externas que debes instalar por separado. Verifícalas con dream-cycle doctor.

| Herramienta | Qué es | Instalación | |---|---|---| | repo2rlenv | convierte repos en entornos RL evaluables (sintetiza el corpus pr_diff) | uv tool install repo2rlenv==0.8.3 (PyPI, requiere Python ≥ 3.12) | | harbor | runner de agentes sobre entornos (calibración oracle/nop) | uv tool install harbor | | gh | GitHub CLI autenticado (minado de PRs) — ≥ 2.49 (pr list --json baseRefOid) | releases de cli/cli + gh auth login | | docker | construye y corre los entornos de cada tarea | Docker Desktop o Engine, con el daemon corriendo |

Si una herramienta no está en PATH (p. ej. la usas desde un venv local), apunta a ella con su variable de entorno:

| Variable de entorno | Efecto | |---|---| | REPO2RLENV_BIN | ruta al binario repo2rlenv (p. ej. .venv/bin/repo2rlenv) | | HARBOR_BIN | ruta al binario harbor | | GH_BIN | ruta al binario gh (GitHub CLI) | | DOCKER_BIN | ruta al binario docker | | RUNS_DIR | sobreescribe el directorio de result.json del gate (máxima precedencia) | | RADAR_JSON | radar: emite el reporte como JSON a stdout | | RADAR_NO_WRITE | radar: no escribe dream-cycle-radar-latest.json | | BENCH_JSON | gate: emite el summary como JSON a stdout | | BENCH_NO_WRITE | gate: no escribe result.json | | DOCKER_HOST | socket de docker (default unix:///var/run/docker.sock) |

Resolución de binarios: variable de entorno → .dream-cycle/config.json (bins.<name>) → PATH.

Versiones de repo2rlenv

repo2rlenv saca releases con frecuencia. Este paquete NO lo congela (es una herramienta externa, no una dependencia npm); el manejo es por capas:

1. Versión probada declarada: el pipeline está validado E2E contra repo2rlenv 0.8.3 — por eso la instalación recomendada lleva pin. doctor muestra la versión detectada y avisa si difiere de la probada.
2. validate después de generate: run ejecuta el validate del propio repo2rlenv sobre el corpus recién sintetizado y aborta si el formato no cierra (exit 1).
3. Calibración oracle/nop como red final: aunque el formato pase, un cambio de comportamiento upstream que rompa los rewards cae en el gate — oracle que no llega a ~1.0 o nop que no da 0.0 abortan el run (exits 3–5).

Para adoptar una versión nueva: instalarla, re-correr dream-cycle run contra un repo conocido, y si el gate pasa, actualizar el pin (README) y R2E_TESTED_VERSION (lib/doctor.mjs).

Subcomandos

dream-cycle doctor [--json]

Diagnostica node (≥20), docker (CLI + daemon), gh (CLI + auth), harbor y repo2rlenv. Exit 0 si todo está, 1 si falta algo.

dream-cycle run <owner/repo> [--limit N] [--since YYYY-MM-DD]

Pipeline completo contra cualquier repo. --since es el guardarraíl de contaminación: solo se minan PRs posteriores a esa fecha (default 2026-02-01).

dream-cycle run astral-sh/ruff --limit 20 --since 2026-02-01

| Exit | Significado | |---|---| | 0 | éxito | | 1 | subproceso/genérico (generate/validate fallaron, binarios faltantes) | | 2 | error de uso | | 3 | corpus insuficiente (< minTasks tareas antes o después de curar) | | 4 | gate oracle FALLÓ tras curación — investigar | | 5 | el gate PASÓ con el agente nulo — el corpus NO discrimina |

dream-cycle radar [--runs-dir <dir>] [--benchmark <name>] [--epsilon <n>] [--target <reward>]

Radar reactivo: compara los result.json del gate entre runs y declara gaps (regression, stagnation, capability_gap, coverage_gap, trust_gap) con un borrador de issue cada uno. Exit 1 = hay gaps (señal, no error).

dream-cycle init

Crea .dream-cycle/ con config.json (defaults), corpus/, jobs/, runs/ y un .gitignore. Idempotente: nunca pisa un config existente. No es prerequisito — sin config todo funciona con los defaults.

.dream-cycle/ y qué se commitea

.dream-cycle/
├── config.json    # SÍ se commitea (paths, bins, defaults del proyecto)
├── .gitignore     # ignora los tres de abajo
├── corpus/        # artefactos locales — NO
├── jobs/          # jobs harbor — NO
└── runs/          # result.json del gate — decide el humano (sirven de historial del radar)

Protocolo de honestidad

• Curación declarada: las tareas inevaluables (oracle < 0.999 o sin reward) se excluyen, pero la exclusión queda VISIBLE en tasksExcluded del result.json y cambia el corpusVersion (que se calcula sobre el set efectivo).
• Falsificación nop obligatoria: un corpus solo vale si el agente nulo lo FALLA. Si el nop pasa, el corpus no discrimina y el pipeline aborta (exit 5).
• Targets antes de resultados: el gate en modo agent se NIEGA a gatear sin un --target-reward-mean declarado por el invocador (anti-fabricación).
• El radar propone, el humano decide: los issueDraft requieren revisión humana antes de abrirse; el radar nunca abre issues ni decide qué construir.

Seguridad

• NUNCA tokens en archivos: el overlay de compose para repos privados solo contiene el placeholder literal ${GITHUB_TOKEN}; compose lo interpola desde el entorno del proceso. El token jamás toca disco.
• Nota: un build-arg queda visible en los metadatos de la imagen local (docker history); aceptable para runs locales — no publicar esas imágenes.
• El brazo agente opcional con claude-code se invoca a mano con placeholder:

harbor run -p <corpus> -a claude-code -m <model> \
  --ae CLAUDE_CODE_OAUTH_TOKEN=<token> --ae CLAUDE_FORCE_OAUTH=1 \
  --env docker -o <jobs>/dc-<slug>-agent

Licencia

MIT