turbo rig / deep dive — the logic of everythingla lógica de todo

00What Turbo Rig is00Qué es Turbo Rig

Not a framework, not a runtime, not a product. A single git repo of contracts and scripts that wraps around existing agent harnesses.No es un framework, no es un runtime, no es un producto. Un único repo git de contratos y scripts que envuelve a los harnesses de agentes existentes.

The one-sentence definition, from the rig's own explainer: a harness drives an agent; a rig drives your harnesses. You have three AI coding agents that could each do anything — which is exactly the problem. Without structure you get three harnesses, an inert swarm layer, thousands of lines of shell config, and no reliable way to know if an agent's work is actually correct. The rig is the structure.La definición en una frase, del propio explicador del rig: un harness conduce un agente; un rig conduce tus harnesses. Tienes tres agentes de código con IA que podrían cada uno hacer cualquier cosa — que es exactamente el problema. Sin estructura terminas con tres harnesses, una capa de enjambre inerte, miles de líneas de configuración shell, y ninguna forma confiable de saber si el trabajo de un agente es realmente correcto. El rig es la estructura.

Concretely it is a repo (public convention ~/turbo-rig; the founder's clone is ~/rig) containing: a constitution every agent reads, one cross-model verification gate, worktree tooling, observability dashboards, QA report machinery, a schedule of self-checking automations, and a git-versioned memory tier. It has no runtime of its own and nothing to keep alive — the "roads and traffic lights" are git, GitHub, and files; orchestration emerges from shared data rather than from a coordinator.En concreto es un repo (convención pública ~/turbo-rig; el clon del fundador es ~/rig) que contiene: una constitución que todo agente lee, una compuerta de verificación entre modelos, herramienta de worktrees, dashboards de observabilidad, maquinaria de reportes QA, un calendario de automatizaciones auto-verificantes y un nivel de memoria versionado en git. No tiene runtime propio ni nada que mantener vivo — las "carreteras y semáforos" son git, GitHub y archivos; la orquestación emerge de los datos compartidos, no de un coordinador.

Everything the rig replaced was subtracted with reasons: the claude-flow/ruflo swarm layer (native harness features replaced it; its 689 shell aliases were collapsed into one on-demand file), Aider (unmaintained), Grok Build (walled beta), NVIDIA Avo (research system, no repo — but two of its ideas were stolen: persistent memory and a redirecting supervisor). The rig's own docs/WHY-NOT-THOSE-TOOLS.md keeps the full audit trail.Todo lo que el rig reemplazó fue sustraído con razones: la capa de enjambre claude-flow/ruflo (las funciones nativas del harness la reemplazaron; sus 689 aliases de shell se colapsaron en un archivo bajo demanda), Aider (sin mantenimiento), Grok Build (beta cerrada), NVIDIA Avo (sistema de investigación, sin repo — pero dos de sus ideas fueron robadas: memoria persistente y un supervisor que redirige). El propio docs/WHY-NOT-THOSE-TOOLS.md del rig conserva la pista de auditoría completa.

01Architecture — Triangle · Spine · Loop · Planes · Background01Arquitectura — Triángulo · Espina · Bucle · Planos · Fondo

Five named tiers. Every file in the repo belongs to exactly one of them.Cinco niveles con nombre. Cada archivo del repo pertenece a exactamente uno de ellos.

┌───────────────────────── MAC (control plane) ──────────────────────────┐
│  ZCode (cockpit)      Claude Code (builder+reviewer)    Codex (dormant)│
│        └───────────────┬──────────┴─────────────┘                       │
│              AGENTS.md constitution (~/turbo-rig — this repo)           │
│   skills (~/.agents/skills) · memory/ · specs/ · runbooks/ · qa/        │
│   gate: scripts/review.sh          worktrees: scripts/wt.sh             │
└───────────────────────────────┬─────────────────────────────────────────┘
                                │ git pull / gh
┌────────────────────── REMOTE (execution plane) ────────────────────────┐
│  VPS via DevPod SSH · gh Codespaces                                    │
│  builds, containers, yolo-permission agents — never on the Mac         │
└─────────────────────────────────────────────────────────────────────────┘

The Triangle — roles are fixed, harnesses are swappableEl Triángulo — los roles son fijos, los harnesses intercambiables

Two inviolable roster rules: at least two model families, and the reviewer is never the builder's family (collapsing to one family is self-review — it deletes the cross-review effect the gate exists for). And there's a documented GLM-free variant for users who avoid Chinese vendors: Codex builds, Claude reviews. Swapping the roster is a ~15-minute recipe (runbooks/swap-roster.md) — machinery never changes, only the table does.Dos reglas de roster inviolables: al menos dos familias de modelos, y el revisor nunca es de la familia del constructor (colapsar a una sola familia es auto-revisión — borra el efecto de revisión cruzada por el que existe la compuerta). Y hay una variante documentada sin GLM para quienes evitan proveedores chinos: Codex construye, Claude revisa. Cambiar el roster es una receta de ~15 minutos (runbooks/swap-roster.md) — la maquinaria nunca cambia, solo cambia la tabla.

02The constitution — AGENTS.md02La constitución — AGENTS.md

The single source of truth for how agents behave. Tool-specific files import it; nothing duplicates it (drift is the enemy).La única fuente de verdad sobre cómo se comportan los agentes. Los archivos específicos de cada herramienta lo importan; nada lo duplica (la deriva es el enemigo).

At the top sits an ## Invariants section — machine-read by the gate itself (see §3): every review of the rig injects those invariants into the reviewer prompt, scrubbed and fenced as data. Violations are automatic REVISE. This is a repo writing laws for its own reviewer.Al inicio vive una sección ## Invariants — leída por máquina por la propia compuerta (ver §3): cada revisión del rig inyecta esos invariantes en el prompt del revisor, lavados y cercados como datos. Las violaciones son REVISE automático. Es un repo escribiendo leyes para su propio revisor.

The ten lawsLas diez leyes

Queue ownership — the gate log as heartbeatPropiedad de cola — el log de la compuerta como latido

A doctrine born from a real incident: a cockpit misread a live gating cycle as an idle queue and offered a sweep that would have double-gated two in-flight PRs. The fix: read the gate log as a heartbeat, not a snapshot. A gate-log run for a PR in the last 30 minutes from a different worktree means another session owns it mid-loop — the gate refuses (exit 4). Your own worktree's fresh runs are your own loop. Override: GATE_FORCE=1.Una doctrina nacida de un incidente real: una cabina malinterpretó un ciclo de compuerta activo como una cola ociosa y ofreció un barrido que habría pasado dos PRs en vuelo por doble compuerta. La corrección: leer el log de la compuerta como un latido, no como una instantánea. Una corrida del gate-log para un PR en los últimos 30 minutos desde otro worktree significa que otra sesión lo posee a medio bucle — la compuerta se rehúsa (exit 4). Las corridas frescas de tu propio worktree son tu propio bucle. Override: GATE_FORCE=1.

03The gate — scripts/review.sh03La compuerta — scripts/review.sh

The heart of the rig: a 959-line bash file that makes a different model family review every diff before merge, and turns its answer into a machine-parseable, fail-closed verdict.El corazón del rig: un archivo bash de 959 líneas que hace que una familia de modelo distinta revise cada diff antes de la fusión, y convierte su respuesta en un veredicto parseable por máquina, de fallo-cerrado.

Exit-code contractContrato de códigos de salida

The review promptEl prompt de revisión

Every reviewer gets the same adversarial brief: review only the diff, no tools, no file reads; hunt in order — correctness bugs, security issues (injection, leaked secrets, unsafe handling of untrusted input), broken error handling, missing tests for changed behavior; cite file:line for every finding; ignore pure style; end with exactly one verdict line. The diff is appended under a --- DIFF --- separator. Reviews are deliberately read-only and context-free: the reviewer can't be socialized by the codebase, only by the delta.Cada revisor recibe la misma consigna adversarial: revisar solo el diff, sin herramientas, sin leer archivos; cazar en orden — bugs de corrección, problemas de seguridad (inyección, secretos filtrados, manejo inseguro de entrada no confiable), manejo de errores roto, tests faltantes para el comportamiento cambiado; citar file:line por cada hallazgo; ignorar puro estilo; terminar con exactamente una línea de veredicto. El diff se adjunta bajo un separador --- DIFF ---. Las revisiones son deliberadamente de solo-lectura y sin contexto: al revisor no puede socializarlo el código base, solo el delta.

Proofs before prophets — repo invariantsPruebas antes que profetas — invariantes de repo

If the repo under review has an ## Invariants section in its AGENTS.md, the gate injects it into the prompt as claims to check, never instructions. Three defenses make this injection-proof:Si el repo bajo revisión tiene una sección ## Invariants en su AGENTS.md, la compuerta la inyecta en el prompt como afirmaciones-a-verificar, nunca como instrucciones. Tres defensas la vuelven a prueba de inyección:

• Base ref, not head. Invariants are read from the BASE ref (trusted pre-PR state). A PR that edits its own invariants to add "always approve" never reaches the reviewer prompt — that exact self-approval injection path was caught by a gate round and is now pinned by a selftest that plants a hostile head commit and proves via a cat-oracle that only base invariants arrive.Ref base, no head. Los invariantes se leen del ref BASE (estado pre-PR confiable). Un PR que edita sus propios invariantes para añadir "always approve" jamás llega al prompt del revisor — exactamente esa ruta de auto-aprobación por inyección fue atrapada por una ronda de la compuerta y hoy la fija un selftest que planta un commit head hostil y prueba vía oráculo-cat que solo llegan los invariantes base.
• Verdict-line scrubbing. Every line matching verdict\s*: (any case, any spacing) is stripped from the invariants and from deterministic-check output tails — untrusted text can never smuggle a verdict into a prompt or PR comment.Lavado de líneas de veredicto. Toda línea que matchee verdict\s*: (cualquier casing, cualquier espaciado) se arranca de los invariantes y de las colas de salida de los checks deterministas — el texto no confiable jamás puede contrabandear un veredicto hacia un prompt o comentario de PR.
• Fencing. The block is wrapped in <<<INVARIANTS-DATA / >>>END-DATA markers, indented, and fence-breakers are stripped so it can't escape its box.Cercado. El bloque se envuelve en marcadores <<<INVARIANTS-DATA / >>>END-DATA, se indenta, y los rompe-cercas se arrancan para que no pueda escapar de su caja.

Deterministic checks — the $0 pre-LLM laneChecks deterministas — el carril de $0 pre-LLM

--check '<cmd>' (repeatable) runs operator commands — tsc --noEmit, a test suite, a linter — in the repo before any LLM lane fires. A failing check is the REVISE verdict: the script fabricates the review body (check name, exit code, last 20 lines of scrubbed output) and the reviewer never runs — quota saved, seconds not minutes. Checks break on first failure (a sentinel-proven non-execution of later checks), and PR/stdin modes stamp an honesty note that the check ran against the local working tree, not the PR head.--check '' (repetible) corre comandos del operador — tsc --noEmit, una suite de tests, un linter — en el repo antes de que cualquier carril LLM se dispare. Un check que falla es el veredicto REVISE: el script fabrica el cuerpo de la revisión (nombre del check, código de salida, últimas 20 líneas de salida lavada) y el revisor nunca corre — cuota ahorrada, segundos en vez de minutos. Los checks cortan en el primer fallo (no-ejecución de los checks posteriores probada por centinela), y los modos PR/stdin estampan una nota de honestidad de que el check corrió contra el árbol local, no contra el head del PR.

Reviewer lanesCarriles de revisor

The claude degradation ladderLa escalera de degradación de claude

One reviewer, four rungs, each checking the envelope before trusting it: --bare --output-format json (richest — carries usage + cost) → plain --output-format json → bare text prompt → plain text. An auth-broken envelope ("Not logged in" in result) is discarded at the parse step, not mistaken for an empty review. Every degrade costs only the usage row — the verdict path survives any CLI quirk.Un revisor, cuatro peldaños, cada uno verificando el sobre antes de confiar en él: --bare --output-format json (el más rico — lleva uso + costo) → --output-format json plano → prompt de texto plano → texto plano. Un sobre con auth rota ("Not logged in" en result) se descarta en el paso de parse, no se confunde con una revisión vacía. Cada degradación cuesta solo la fila de uso — la ruta del veredicto sobrevive cualquier rareza del CLI.

The codex completeness proofLa prueba de completitud de codex

codex streams JSON events; the review text is the last agent_message, and the proof the stream wasn't truncated mid-flight is the terminal turn.completed event — detected by whether the usage parser produced output, not by grepping a brittle literal. Exit 0 alone is insufficient: a killed stream can leave a parseable-but-partial message. Incomplete → full fallback re-run (double latency, the cost of a schema shift is a second call, never the verdict); still empty → failure (return 1) so auto can fall through to the other reviewer. The scratch-anchor trick: codex demands a git cwd, so the gate mints a throwaway empty repo in mktemp space — anchoring in the reviewed repo would only grant unneeded read scope to a reviewer forbidden from reading anything.codex transmite eventos JSON; el texto de la revisión es el último agent_message, y la prueba de que el flujo no fue truncado a medio vuelo es el evento terminal turn.completed — detectado por si el parser de uso produjo salida, no grepeando un literal frágil. Exit 0 solo es insuficiente: un flujo matado puede dejar un mensaje parseable-pero-parcial. Incompleto → re-ejecución completa de fallback (doble latencia; el costo de un cambio de esquema es una segunda llamada, nunca el veredicto); aún vacío → fallo (return 1) para que auto pueda caer al otro revisor. El truco del ancla de rasguño: codex exige un cwd git, así que la compuerta acuña un repo vacío desechable en espacio mktemp — anclar en el repo revisado solo le daría alcance de lectura innecesario a un revisor al que le está prohibido leer.

Quota-aware auto dispatchAuto-despacho consciente de cuota

--reviewer auto (the default) keeps the gate inside the subscription. It reads Claude's live 7-day plan utilization — OAuth token pulled from macOS Keychain, called against Anthropic's own usage endpoint, token traveling via curl's stdin config so it never appears in ps — and if utilization is ≥ GATE_QUOTA_THRESHOLD (default 75%) and codex is authed, it dispatches codex for that run and says why. Any probe failure (no keychain, no token, bad JSON) means "signal absent" → stay claude-first. The dispatch function is pure arithmetic over two arguments, which is exactly why it's unit-testable from selftest.--reviewer auto (el default) mantiene la compuerta dentro de la suscripción. Lee la utilización viva del plan de Claude a 7 días — token OAuth jalado del Keychain de macOS, consultando el propio endpoint de uso de Anthropic, el token viaja vía la config stdin de curl para que nunca aparezca en ps — y si la utilización es ≥ GATE_QUOTA_THRESHOLD (default 75%) y codex está autenticado, despacha codex para esa corrida y dice por qué. Cualquier fallo de sonda (sin keychain, sin token, JSON malo) significa "señal ausente" → mantener claude-primero. La función de despacho es aritmética pura sobre dos argumentos — exactamente por eso es unit-testeable desde el selftest.

Sweep modeModo barrido

--sweep walks every open PR (limit 50), skips any that already carries a gate verdict comment (force re-review with --pr N), gates the rest, and classifies each child run: ok (exit 0), fail (verdict or error), or skip (ownership refusal exit 4). The summary line is faithful by construction — four distinct shapes for "nothing open / nothing reviewed / mixed / clean" so a no-op can never read as a green sweep.--sweep recorre cada PR abierto (límite 50), se salta los que ya llevan un comentario de veredicto de la compuerta (forzar re-revisión con --pr N), compuerta al resto y clasifica cada corrida hija: ok (exit 0), fail (veredicto o error) o skip (rechazo de propiedad exit 4). La línea de resumen es fiel por construcción — cuatro formas distintas para "nada abierto / nada revisado / mixto / limpio", así un no-op nunca puede leerse como un barrido verde.

The audit trail — gate-log.jsonlEl rastro de auditoría — gate-log.jsonl

Every run appends one JSON row to ~/.local/state/turbo-rig/gate-log.jsonl: timestamp, repo (worktree basename — the ownership key), target (pr#N or base..head), reviewer, verdict, in/cached/out tokens, API-equivalent cost, duration, model. The log is append-only truth: it feeds ownership checks, both dashboards, the digest's merge queue, merge-QA reports, and the weekly retro. Check-decided runs log a zero-token row with reviewer: check — the trail is complete even when no LLM ran.Cada corrida agrega una fila JSON a ~/.local/state/turbo-rig/gate-log.jsonl: timestamp, repo (nombre base del worktree — la llave de propiedad), target (pr#N o base..head), revisor, veredicto, tokens in/cached/out, costo API-equivalente, duración, modelo. El log es verdad de solo-agregar: alimenta los checks de propiedad, ambos dashboards, la cola de fusión del digest, los reportes merge-QA y el retro semanal. Las corridas decididas-por-check loguean una fila de cero tokens con reviewer: check — el rastro queda completo incluso cuando ningún LLM corrió.

Anatomy of a gate-log rowAnatomía de una fila del gate-log

One JSON line per run — the atom every downstream tool joins on:Una línea JSON por corrida — el átomo sobre el que se une toda herramienta aguas abajo:

{"ts": "2026-09-21T22:06:15",            // naive LOCAL time — the tokens.py convention
 "repo": "prd25-og-locale",                // worktree basename — the ownership key + lane label
 "target": "pr#429" | "main..HEAD",        // PR mode vs branch mode
 "reviewer": "claude" | "codex" | "check", // WHO decided — "check" = deterministic lane
 "result": "GATE: APPROVED (reviewer: claude)",
 "in": 2, "cached": 54082, "out": 1922,   // reviewer-reported token burn
 "cost_usd": 0.4788, "duration_ms": 29495,
 "model": "claude-haiku-4-5-20251001,claude-opus-5[1m]"}

Downstream consumers: ownership check (30-min window), tokens.py (gate burn), activity.py (verdicts, rounds, rhythm — prefix-anchored parse so a verdict word quoted mid-string can't flip it), digest merge queue (PRs ⋈ verdicts, with the rig → turbo-rig alias join), merge-qa (per-PR trajectory), weekly retro (REVISE defect classes). Append-only: nothing ever rewrites it.Consumidores aguas abajo: check de propiedad (ventana de 30 min), tokens.py (consumo de la compuerta), activity.py (veredictos, rondas, ritmo — parse anclado por prefijo para que una palabra de veredicto citada a mitad de cadena no lo vuelque), cola de fusión del digest (PRs ⋈ veredictos, con el join del alias rig → turbo-rig), merge-qa (trayectoria por PR), retro semanal (clases de defecto REVISE). Solo-agregar: nada lo reescribe jamás.

Hygiene details that matterDetalles de higiene que importan

• Scratch-anchor cleanup. Reviewer subshells register throwaway dirs in a side-channel anchor file; the EXIT trap deletes only paths carrying the rig's own .rig-scratch marker under the temp base — a stray append can never turn cleanup into rm -rf of a real working tree. The temp base is derived from where mktemp actually created the anchor file (self-truthing, immune to TMPDIR quirks).Limpieza del ancla de rasguño. Los subshells del revisor registran directorios desechables en un archivo ancla de canal lateral; la trampa de EXIT borra solo las rutas que llevan el marcador propio .rig-scratch bajo la base temporal — un append descarriado jamás puede convertir la limpieza en un rm -rf de un árbol de trabajo real. La base temporal se deriva de dónde mktemp creó de verdad el archivo ancla (auto-veraz, inmune a las rarezas de TMPDIR).
• Stderr narration. All progress chatter goes to stderr; piped stdout carries only the review + verdict — scriptable by contract.Narración en stderr. Todo el ruido de progreso va a stderr; el stdout entubado lleva solo la revisión + veredicto — scripteable por contrato.
• Signal-safe traps. Separate INT/TERM traps route through the EXIT trap so Ctrl-C can't leak scratch dirs.Trampas a prueba de señales. Trampas INT/TERM separadas enrutan por la trampa de EXIT para que Ctrl-C no pueda regar directorios de rasguño.
• PR comments carry lane attribution (--builder 'ZCode (GLM)') and the usage line — GitHub becomes the communication channel and state machine.Los comentarios de PR llevan atribución de carril (--builder 'ZCode (GLM)') y la línea de uso — GitHub se vuelve el canal de comunicación y la máquina de estados.

--selftest: the gate gates itself--selftest: la compuerta se compuerta a sí misma

~280 lines of fixture-pinned proofs, no network: codex stream parsers (agent message last-wins, usage mapping, old schema alias tolerance); scratch-anchor round-trip; fail-closed proofs (a reviewer that exits 0 with empty output must return exactly 1, not 2; a truncated stream must fail; empty stdin must exit 2); auto-dispatch order (forced quota + fake codex must pick the codex lane — a claude-first regression would pass every other assertion while defeating the feature); definition-order pinning (a helper defined after its call site is a silent misfire — caught twice in real bugs); ownership fixtures (fresh-foreign flagged, own-fresh and stale-foreign pass); invariants extraction and hostile-scrub both fences; the cat-oracle injection e2e; deterministic-check rc contract; trap safety with a decoy directory that must survive. The platform runs a weekly gate readiness canary on top — because the reviewer lane's demonstrated failure mode is silent auth rot.~280 líneas de pruebas fijadas a fixtures, sin red: parsers de flujo codex (agent message last-wins, mapeo de uso, tolerancia a alias de esquema viejo); ida-y-vuelta del ancla de rasguño; pruebas de fallo-cerrado (un revisor que sale 0 con salida vacía debe retornar exactamente 1, no 2; un flujo truncado debe fallar; stdin vacío debe salir 2); orden del auto-despacho (cuota forzada + codex falso debe elegir el carril codex — una regresión claude-primero pasaría todas las demás aserciones mientras derrota la función); fijado del orden de definición (un helper definido tras su punto de llamada es un disparo silencioso — atrapado dos veces en bugs reales); fixtures de propiedad (ajeno-fresco marcado, propio-fresco y ajeno-rancio pasan); extracción de invariantes y lavado hostil de ambas cercas; la inyección e2e del oráculo-cat; contrato rc del check determinista; seguridad de traps con un directorio señuelo que debe sobrevivir. La plataforma corre encima un canario semanal de disposición de la compuerta — porque el modo de falla demostrado del carril revisor es la rotación silenciosa de auth.

04Isolation, onboarding & the planes04Aislamiento, onboarding y los planos

Worktrees so parallel writers can't collide; a 30-second onboarding script; a bootstrap that turns any machine into a rig plane; secrets encrypted at rest; heavy work shipped off-box.Worktrees para que los escritores en paralelo no colisionen; un script de onboarding de 30 segundos; un bootstrap que convierte cualquier máquina en un plano del rig; secretos cifrados en reposo; el trabajo pesado enviado fuera de la caja.

05Observability — tokens.py · activity.py · digest.sh05Observabilidad — tokens.py · activity.py · digest.sh

Two live dashboards and one morning gatherer. One answers "what did the models burn?", the other "what did the rig DO?", and the digest turns both into the day's briefing.Dos dashboards vivos y un recolector matutino. Uno responde "¿qué quemaron los modelos?", el otro "¿qué HIZO el rig?", y el digest convierte ambos en el informe del día.

06QA machinery — qa-report.sh · merge-qa.sh · configs/06Maquinaria QA — qa-report.sh · merge-qa.sh · configs/

Proofs before prophets, mechanized: QA reports assemble what is provable — fresh live evidence — and leave judgment to explicitly-marked agent sections.Pruebas antes que profetas, mecanizado: los reportes QA ensamblan lo demostrable — evidencia viva fresca — y dejan el juicio a secciones de agente explícitamente marcadas.

07scripts/railway-pr-env-sweep.py

A self-healing control loop for Railway preview environments — and a precise little state machine about when it's allowed to touch a database variable.Un lazo de control auto-reparante para entornos preview de Railway — y una pequeña máquina de estados precisa sobre cuándo le es permitido tocar una variable de base de datos.

The problem: Railway PR environments fork production's variables, so they inherit DATABASE_URL with the private hostname postgres.railway.internal — which resolves, per-environment, to that env's own empty Postgres. The app boots, migrations run, and every login 401s against zero users. Rather than per-repo CI wiring, this one central script sweeps every configured project's PR environments and repoints DATABASE_URL at the live database's public endpoint (Railway auto-redeploys on variable change; the script never triggers deploys). Idempotent and safe on a ~30-minute schedule — it also catches Railway's late variable-fork overwrite that one-shot wiring misses.El problema: los entornos PR de Railway bifurcan las variables de producción, así que heredan DATABASE_URL con el hostname privado postgres.railway.internal — que resuelve, por entorno, al propio Postgres vacío de ese env. La app arranca, corren las migraciones y cada login da 401 contra cero usuarios. En lugar de cableado de CI por repo, este único script central barre los entornos PR de cada proyecto configurado y repunta DATABASE_URL al endpoint público de la base viva (Railway auto-re-despliega al cambiar una variable; el script jamás dispara deploys). Idempotente y seguro en calendario de ~30 minutos — también atrapa la sobre-escritura tardía de variables-fork de Railway que el cableado de un solo tiro se pierde.

The logic that earns its keep — three-way state classification per environment, never hardcoded per branch:La lógica que se gana su sueldo — clasificación de estado en tres vías por entorno, jamás hardcodeada por rama:

• already wired — URL equals the live-DB URL: no-op (and by construction nothing env-local to lose).ya cableado — la URL iguala la URL de la BD viva: no-op (y por construcción no hay nada env-local que perder).
• fork default — hostname is the internal one: rewire. Even a PR_ENV_DB_PIN present here is treated as inherited from production (a pin only means something with a deliberate override).fork default — el hostname es el interno: re-cablear. Incluso un PR_ENV_DB_PIN presente aquí se trata como heredado de producción (un pin solo significa algo con un override deliberado).
• deliberate override — a pin plus a non-default URL: skip with a note. Someone pointed this env elsewhere on purpose.override deliberado — un pin más una URL no-default: saltar con nota. Alguien apuntó este env a otra parte a propósito.
• env-local — a URL that is neither unset, the live wiring, nor the fork default: this env has its own data, and the sweep says what destroying it would lose.env-local — una URL que no es ni unset, ni el cableado vivo, ni el fork default: este env tiene sus propios datos, y el barrido dice qué perdería destruirlo.

Before any destructive consequence, backup freshness is checked lazily (only paid when some env is actually env-local): the per-env R2 dump age, fetched with R2 creds pulled from the Railway source service — and every distinct way freshness can be unknown gets its own named reason ("misconfiguration must not hide behind 'unavailable'"). Pre-rewire env-local data gets an explicit "orphaned by this rewire — its dump is the only surviving copy" note. Operational hygiene: the API 403s python's default User-Agent (custom UA), credential-bearing URLs are never printed (only hostnames), the Railway token is stripped from the child environment so the backup tool can't act with the sweep's authority, one bad env never aborts the project's others — and an errored env marks the run "changed" so an incomplete sweep can never report a clean no-op. The selftest mocks the GraphQL transport and proves the write path issues exactly one correct upsert.Antes de cualquier consecuencia destructiva, la frescura del respaldo se verifica perezosamente (solo se paga cuando algún env es de verdad env-local): la edad del dump R2 por env, traída con credenciales R2 jaladas del servicio fuente de Railway — y cada forma distinta en que la frescura puede ser desconocida recibe su propia razón nombrada ("una mala configuración no debe esconderse tras 'no disponible'"). Los datos env-local pre-rewire reciben una nota explícita de "huérfanos por este rewire — su dump es la única copia superviviente". Higiene operativa: la API le da 403 al User-Agent default de python (UA custom), las URLs con credenciales jamás se imprimen (solo hostnames), el token de Railway se desprende del entorno hijo para que la herramienta de respaldo no pueda actuar con la autoridad del barrido, un env malo jamás aborta a los demás del proyecto — y un env con error marca la corrida como "changed" para que un barrido incompleto jamás reporte un no-op limpio. El selftest simula el transporte GraphQL y prueba que la ruta de escritura emite exactamente un upsert correcto.

08automations/ — the background tier08automations/ — el nivel de fondo

Nine scheduled tasks. The portability insight: platform automations are workspace- and machine-bound; what travels is the file — exact prompts plus scheduling recipes. Rebuilding the tier on a new machine is minutes, not archaeology.Nueve tareas programadas. La idea de portabilidad: las automatizaciones de plataforma viven atadas al workspace y a la máquina; lo que viaja es el archivo — prompts exactos más recetas de calendarización. Reconstruir el nivel en una máquina nueva toma minutos, no arqueología.

09The docs layer09La capa de docs

Manuals, design docs, runbooks, specs — each with a distinct job.Manuales, documentos de diseño, runbooks, specs — cada uno con un trabajo distinto.

10State map — where truth lives10Mapa de estado — dónde vive la verdad

Law 7: state lives on disk. The rig keeps exactly one home per kind of truth.Ley 7: el estado vive en disco. El rig mantiene exactamente un hogar por tipo de verdad.

Plus the machine-level homes bootstrap wires: ~/.agents/skills (single source, symlinked), the OS keychain via secret.sh, and the spine pointers in each harness's global instructions.Más los hogares a nivel de máquina que cablea el bootstrap: ~/.agents/skills (fuente única, enlazada), el keychain del SO vía secret.sh, y los punteros de espina en las instrucciones globales de cada harness.

The memory system — two stores, one brainEl sistema de memoria — dos almacenes, un cerebro

The rig is deliberately stateless — no daemon, no database, nothing to keep alive. That only works because memory carries the state. There are two stores with a strict division of labor, and their interop is what lets any harness, on any plane, start a fresh context and resume with full knowledge.El rig es deliberadamente sin-estado — sin daemon, sin base de datos, nada que mantener vivo. Eso solo funciona porque la memoria carga el estado. Hay dos almacenes con una división del trabajo estricta, y su interop es lo que permite a cualquier harness, en cualquier plano, arrancar un contexto fresco y reanudar con conocimiento completo.

Division of labor (Law 8: one source of truth per concern)División del trabajo (Ley 8: una fuente de verdad por asunto)

• Canonical, shareable facts — design decisions, machine gotchas, project maps — live in rig memory. Every agent family and every plane reads the same files; git history is the audit trail; the weekly retro and nightly consolidation feed on them.Hechos canónicos compartibles — decisiones de diseño, gotchas de máquina, mapas de proyecto — viven en la memoria del rig. Cada familia de agente y cada plano leen los mismos archivos; la historia de git es la pista de auditoría; el retro semanal y la consolidación nocturna se alimentan de ellos.
• Cockpit-operational knowledge — mp's preferences, session recipes, cross-project links, what was verified when — lives in GLM memory. Claude and Codex don't need it; the cockpit can't work efficiently without it.Conocimiento operacional de cabina — las preferencias de mp, recetas de sesión, enlaces entre proyectos, qué se verificó cuándo — vive en la memoria GLM. Claude y Codex no lo necesitan; la cabina no puede trabajar eficiente sin él.
• Repo-specific facts — stack notes, test commands, deploy gotchas for one repo — go into that repo's own AGENTS.md cheat-sheet (written by init-repo.sh), never into the rig's global memory. The README calls this out explicitly as the cross-contamination vector people miss.Hechos específicos de repo — notas de stack, comandos de test, gotchas de deploy de un solo repo — van en la cheatsheet AGENTS.md de ese repo (escrita por init-repo.sh), jamás en la memoria global del rig. El README lo señala explícitamente como el vector de contaminación cruzada que la gente pasa por alto.

The interop loopsLos bucles de interop

• Capture (session end): a session that discovered a durable fact writes both where it belongs — a dated line or inbox note for the rig store (Law 7), and its own memory file for cockpit-level facts. In practice the cockpit's memory entries act as pointers with context: "Rig 24h stats report 09-22 — HTML in Downloads; verified numbers + full log-source map" points at rig state without duplicating it.Captura (cierre de sesión): una sesión que descubrió un hecho durable lo escribe ambos donde corresponde — una línea fechada o nota de bandeja para el almacén del rig (Ley 7), y su propio archivo de memoria para hechos de nivel cabina. En la práctica, las entradas de memoria de la cabina actúan como punteros con contexto: "Rig 24h stats report 09-22 — HTML en Downloads; números verificados + mapa completo de fuentes de log" apunta a estado del rig sin duplicarlo.
• Consolidation (nightly): the 23:30 automation folds inbox → decisions/gotchas/project-index, deletes fully-captured inbox files older than 14 days, and commits. Uncertain facts become open questions in gotchas.md rather than asserted truths. The Friday weekly retro then reads inbox digests, the gate log, and both harnesses' session logs (ZCode rollouts + Claude projects) to synthesize defect classes and amendment candidates — it is specced to consume both memory worlds.Consolidación (nocturna): la automatización de 23:30 dobla bandeja → decisions/gotchas/project-index, borra archivos de bandeja de >14 días totalmente capturados y commitea. Los hechos inciertos se vuelven preguntas abiertas en gotchas.md en vez de verdades afirmadas. El retro semanal del viernes lee entonces los digests de bandeja, el log de la compuerta y los logs de sesión de ambos harnesses (rollouts de ZCode + projects de Claude) para sintetizar clases de defecto y candidatas de enmienda — está specado para consumir ambos mundos de memoria.
• Recall (session start): the cockpit starts from its own auto-loaded index (fast, private), then opens rig memory files for canonical state — the two-pass law applies to the rig store. Cross-session cockpit recall also exists for hand-offs between ZCode sessions.Recall (inicio de sesión): la cabina arranca desde su propio índice autocargado (rápido, privado), luego abre archivos de memoria del rig para el estado canónico — la ley de dos pasadas aplica al almacén del rig. El recall entre sesiones de cabina también existe para hand-offs entre sesiones de ZCode.
• Precedence: when the two stores disagree, git-versioned rig memory wins. Cockpit entries are operational context, never a second copy of the truth — that rule is what keeps 200+ private files from forking the rig's history.Precedencia: cuando los dos almacenes discrepan, gana la memoria del rig versionada en git. Las entradas de cabina son contexto operacional, jamás una segunda copia de la verdad — esa regla es lo que evita que 200+ archivos privados bifurquen la historia del rig.

11The principles that recur11Los principios que reaparecen

Read across all 20+ files, the same logic shows up everywhere. These are the rig's actual design language.Leídos a través de los más de 20 archivos, la misma lógica aparece en todas partes. Este es el lenguaje de diseño real del rig.