oficina-opencode 0.0.0-stage → 2.0.0

package/skills/oficina/reference/mesh.md

@@ -0,0 +1,345 @@
+# Capa 2-3 — El mesh (v2)
+
+Detalle de la malla: bus, fichas, roster, leases, spawn policy, idle pool.
+
+---
+
+## La ficha: schema único
+
+Venga el rol de agency-agents o de la factory, se materializa en la **misma** `Ficha`. Esa unificación es lo que permite que el bus, el matching de ayuda, la rotación y los coordinadores no necesiten saber el origen de nada.
+
+```yaml
+id: e-frontend          # id de despliegue, único por corrida
+role: frontend-developer
+display_name: Frontend Developer
+source:
+  kind: agency-agents   # agency-agents | factory
+  division: engineering
+  path: engineering/frontend-developer.md
+  source_prompt: <el system prompt original, verbatim>
+  vibe: <la personality hook de una línea del frontmatter>
+  missions: [<subtítulos de "Core Mission">]
+  deliverables: [<subtítulos de "Technical Deliverables">]
+  rules: [<items de "Critical Rules">]
+capabilities:
+  - react-component-design
+  - css-architecture
+  - accessibility
+tools: [read, glob, grep, edit, write, bash]
+scope:
+  may_touch: ["src/components/**", "src/hooks/**"]
+  forbidden: ["src/server/**", "**/*.env*"]
+can_delegate: true      # este rol puede tirar subagentes nuevos
+delegate_budget: 2
+peers:                  # con quién tiene relación de pares (para pedir ayuda)
+  - e-architect
+  - e-qa
+  - e-security
+must_not:               # límites duros, leídos por los coordinadores
+  - "no editar archivos fuera de may_touch"
+  - "no tocar archivos de forbidden"
+  - "no aprobar tu propio trabajo"
+on_finish: "idle-join"  # al terminar su objetivo entra al pool de ayuda
+escalate_to: coordinator-flow
+```
+
+### Resolución: catálogo primero, factory después
+
+El catálogo de agency-agents tiene **306 agentes en 25 divisiones**. La especialidad real de cada uno está en el **cuerpo**, no en el `description` del frontmatter:
+
+- **Core Mission** → los subtítulos son la especialidad declarada
+- **Technical Deliverables** → lo que sabe producir
+- **Advanced Capabilities** → lo que maneja mejor
+
+El matcher pondera: nombre del rol (40%) · misión literal (35%) · misión conceptual (20%) · cuerpo (5%) · división (0%).
+
+```
+1. CATALOG MATCH (preferido)
+   Buscar en agency-agents/<division>/*.md el agente cuya especialidad
+   declarada en el cuerpo matchea las capacidades pedidas.
+   → source.kind = agency-agents, source_prompt = el prompt original
+
+2. FACTORY (si no hay match, o la cobertura es < 60%)
+   Se genera desde template: system prompt = rol + ficha + working
+   discipline + capabilities + objetivo de la corrida, con la MISMA
+   estructura de 10 secciones que agency-agents.
+   → source.kind = factory
+   Se registra como AGENT-CANDIDATE para promoverlo a skill después
+```
+
+**Regla de cobertura**: antes de desplegar, se calcula qué fracción del objetivo cubre el **panel** (primario + complementos). Si es < 60%, se crea un rol nuevo con factory en vez de forzar un mal match.
+
+Esto evita el "subagente monotono", que es el síntoma exacto del problema original.
+
+### El panel de roles
+
+Un objetivo casi nunca es de un solo dominio. El panel devuelve:
+
+- **primario** — el mejor match global. Se lleva la card.
+- **complementos** — los agentes que cubren lo que el primario NO cubre. Son sus pares en el bus.
+- **sin cubrir** — lo que nadie del panel cubre. Señal de que la card debería partirse en dos.
+
+Ejemplo real:
+
+```
+PIDE: react, form, validation, accessibility, frontend
+
+  PRIMARIO    28%  engineering-section-508-specialist
+              cubre:   form, accessibility
+  + COMPLEM. 23%  engineering-frontend-developer
+              aporta:  react, frontend
+```
+
+### Los 4 artefactos de un agente desplegado
+
+Un agente **no arranca sin `misiones.md`**. Nunca.
+
+| Artefacto | Contenido |
+|---|---|
+| `ficha.md` | Quién sos: rol, especialidad, origen, vibe |
+| `misiones.md` | Tu misión · lo que ya sabés · lo que NO sabés |
+| `protocolo.md` | Cómo trabajás · tu territorio · qué se espera · límites · éxito |
+| `bus.md` | Tu canal: dónde, formato, TTLs, cómo acusar recibo |
+
+Y `briefing.md` con el documento completo, para lectura humana.
+
+### El briefing: orden y mínimo
+
+Cada agente recibe un briefing de **10 secciones en orden fijo**. El orden va de lo más estable a lo más cambiante: un agente lee de arriba hacia abajo y siempre tiene lo que necesita para el paso siguiente.
+
+| # | Sección | Qué le dice |
+|---|---|---|
+| 1 | Quién sos | Rol, especialidad de origen, vibe |
+| 2 | Tu misión | Card, criterios de aceptación numerados, gate |
+| 3 | Lo que ya sabés | Decisiones, restricciones, piezas, trampas |
+| 4 | Lo que NO sabés | Huecos explícitos y a quién preguntarle |
+| 5 | Tu territorio | may_touch / forbidden / prohibiciones de la ficha |
+| 6 | Cómo trabajás | Ciclo, cuándo pedir ayuda, delegar, escalar |
+| 7 | Tu canal | Bus: dónde, formato, TTL, ack |
+| 8 | Qué se espera de vos | handoff.md y evidence.md |
+| 9 | Lo que no podés hacer | Prohibiciones (están en código) |
+| 10 | Cómo se mide que terminaste | Las tres condiciones de terminado |
+
+**Mínimo**: las 10 secciones son requeridas. Si alguna queda vacía, el briefing se marca `INCOMPLETO` y el agente no arranca. Un briefing a medio llenar produce un agente a medio informado, que es peor que no tener agente.
+
+**La sección 3 se alimenta del ledger** (`.oficina/context.md`). Es lo que evita repetir lo ya decidido.
+
+---
+
+## El bus
+
+### Layout
+
+```
+.oficina/
+├── bus/
+│   ├── coord-command/0001-<msgid>.json    # canal del Comandante
+│   ├── coord-arch/0001-<msgid>.json       # canal del Arquitecto
+│   ├── coord-flow/0001-<msgid>.json       # canal del Integrador
+│   └── peer/0001-<msgid>.json             # canal general entre pares
+├── inbox/<agentId>/                       # índice de lo que le llegó
+├── roster.json                            # quién existe, qué puede, qué hace
+├── leases/<taskId>.json                   # lock con TTL
+```
+
+### Envelope
+
+```json
+{
+  "id": "m-0042",
+  "seq": 42,
+  "from": "e-frontend",
+  "to": ["e-architect"],
+  "kind": "HELP_REQUEST",
+  "subject": "T-03",
+  "body": {
+    "need": "convertir este componente a streaming SSR",
+    "why_me": "tengo el contexto del componente pero no el del server"
+  },
+  "reply_to": null,
+  "in_reply_to": null,
+  "ttl_sec": 900,
+  "created_at": "2026-10-21T15:04:00Z",
+  "priority": "normal",
+  "idempotency_key": "T-03-help-request-1",
+  "hops": 0
+}
+```
+
+### Semántica
+
+- **Append-only**: los mensajes nunca se borran, se archivan. `seq` es monótono por canal.
+- **Escritura atómica**: write a `.tmp` + `rename` → nunca hay un JSON partido en el read.
+- **Polling, no push**: cada agente hace `glob` de su inbox cada N turnos.
+- **Ack**: el receptor escribe `inbox/<agentId>/<msgid>.ack`. El emisor ve quién leyó.
+- **TTL**: mensaje expirado = invisible para nuevos lectores, sigue en el log para auditoría.
+- **Idempotency key**: un `HELP_REQUEST` con la misma key no se duplica.
+- **Canal `peer` broadcast**: un `HELP_REQUEST` puede ir a `to: ["*"]` para broadcast de "necesito X" al pool, y el primero que puede toma el lease.
+
+### Tipos de mensaje
+
+| Kind | Quién lo emite | Para qué |
+|---|---|---|
+| `HELP_REQUEST` | cualquier agente | pedir ayuda a un peer o al pool |
+| `HELP_ACCEPT` / `HELP_DECLINE` / `HELP_PARTIAL` / `HELP_QUESTION` | el que recibe | triage del pedido |
+| `QUESTION` / `ANSWER` | agente ↔ coordinador | consultas de dominio |
+| `SPAWN_REQUEST` / `SPAWN_APPROVED` / `SPAWN_REJECTED` | agente ↔ Integrador | gestión de spawns |
+| `CLAIM` / `RELEASE` | agente ↔ Integrador | estado de trabajo |
+| `STATUS` / `NOTICE` | cualquiera | información general |
+
+---
+
+## El protocolo de ayuda
+
+### Cuándo se pide ayuda
+
+Un especialista pide ayuda cuando, **en este orden**:
+
+1. La tarea es de otro dominio → pide al peer de ese dominio
+2. La tarea es de otro dominio y **ese peer no está desplegado** → **despliega uno**
+3. La tarea está en su scope pero ve que otro lo haría mejor → pide
+4. Está bloqueado por una dependencia → pide al dueño del lease
+
+### El que recibe evalúa (no acepta por cortesía)
+
+Al recibir un `HELP_REQUEST`, el receptor **hace su propio triage**:
+
+```
+1. ¿Entiendo la tarea?              → si no: HELP_DECLINE + explicar
+2. ¿Está en mi scope/ficha?          → si no: HELP_DECLINE + sugerir a quién
+3. ¿Puedo hacerlo YA sin romper mi
+   propia card en curso?              → si no: HELP_DECLINE + "cuando termine"
+4. ¿Tengo el contexto necesario?     → si no: HELP_QUESTION (pregunta de vuelta)
+5. ¿Vale la pena? (costo vs. valor)  → si no: HELP_DECLINE + alternativa
+6. ¿Puedo con mi presupuesto?         → si no: HELP_DECLINE + "sin presupuesto"
+```
+
+| Respuesta | Cuándo | Payload |
+|---|---|---|
+| `HELP_ACCEPT` | Puede y corresponde | `scope`, `deadline`, `needs_from_me` |
+| `HELP_DECLINE` | No puede o no le corresponde | `reason`, `alternative`, `available_at` |
+| `HELP_PARTIAL` | Puede una parte | `can_do`, `cannot_do`, `split_suggestion` |
+| `HELP_QUESTION` | No entiende o falta info | `question` — ida y vuelta máximo 2 turnos |
+
+**Anti-deadlock**: una cadena de ayuda (A pide a B, B pide a C) tiene **máximo 2 saltos**. Si se excede, el pedido escala al coordinador de flujo.
+
+**Anti-monotonía en la ayuda**: la rotación de revisor se extiende a la ayuda. Si el mismo par (A↔B) ya se ayudaron 2 veces, el tercer pedido se enruta a un tercero.
+
+---
+
+## Política de spawn
+
+Un especialista puede desplegar un subagente nuevo **solo si**:
+
+1. El rol buscado **no está en el roster activo** (no duplicar)
+2. El rol sale de `agency-agents` por catálogo, o de factory con cobertura ≥ 60%
+3. El presupuesto global lo permite (`max_concurrent`, `max_spawns_total`)
+4. **El deployment es visible en el roster y en el board** — no es invisible
+
+Y **debe reportarlo** al Integrador:
+
+```json
+{
+  "kind": "SPAWN_REQUEST",
+  "requested_role": "motion-designer",
+  "source": {"kind": "agency-agents", "path": "design/motion-designer.md"},
+  "reason": "T-03 necesita transiciones que exceden mi scope de CSS",
+  "budget": {"spawns_used": 1, "spawns_remaining": 1}
+}
+```
+
+El Integrador **aprueba o rechaza**: si la capacidad ya la cubre un peer desplegado, rechaza y le indica a quién preguntar. Esto mata el "cada agente se clona su propio equipo".
+
+**Coherencia clave**: el subagente-account de un subagente es el **mismo `id` de ficha** (no un clon). Hereda la ficha, el bus, el lease, y aparece en el roster. Cuando termina, vuelve al pool de idle.
+
+---
+
+## El pool idle
+
+### Ciclo de vida de un agente
+
+```
+DEPLOYED ──► WORKING ──► (sus cards en DONE) ──► IDLE_AVAILABLE ──► (ayuda) ──► WORKING
+                 │                                                              │
+                 └──► BLOCKED (espera input) ──► IDLE_AVAILABLE                  │
+                                                                                ▼
+                                                                     RETIRED (fin de corrida)
+```
+
+### Registro en el roster
+
+```json
+{
+  "id": "e-frontend",
+  "state": "idle_available",
+  "capabilities": ["react-component-design", "css-architecture"],
+  "idle_since": "2026-10-21T15:22:00Z",
+  "can_accept": true,
+  "lease": null
+}
+```
+
+### Los tres modos de ayudar
+
+1. **Atender un `HELP_REQUEST` dirigido** (to: ["e-frontend"]) → triage → accept/decline
+2. **Atender un broadcast** `to: ["*"]` → el primero que acepta **toma el lease** → los demás lo ven ocupado y se retiran
+3. **Claim proactivo**: si hay work packages sin owner en el board y tu capability matchea el mejor → **reclamás**, avisás al Integrador, y lo hacés. No esperás que te lo asignen.
+
+El modo 3 es lo que convierte la oficina de "N agentes en paralelo" a "N agentes que se acomodan solos según la carga".
+
+---
+
+## Leases
+
+Un agente que trabaja una card **toma un lease** con TTL. El heartbeat lo extiende. Si el agente muere, el lease expira y la card se reasigna.
+
+Sin esto, una card queda trabada por un subagente que murió en silencio.
+
+```
+leases/<taskId>.json
+{
+  "taskId": "T-03",
+  "agentId": "e-frontend",
+  "acquiredAt": "...",
+  "expiresAt": "...",
+  "heartbeatAt": "...",
+  "renewals": 12
+}
+```
+
+**Double-claim**: el lease lo bloquea. Si dos agentes discuten por la misma card, el lease decide — no la discusión.
+
+---
+
+## Deadlock, starvation y agentes muertos
+
+| Problema | Señal | Respuesta |
+|---|---|---|
+| **Deadlock** | dos cards se esperan mutuamente | Romper el ciclo: una cede, o partir una. Lo detecta el Integrador. |
+| **Starvation** | una card espera demasiado | Priorizarla o avisar al Comandante. |
+| **Doble claim** | dos agentes en la misma card | El lease lo bloquea. |
+| **Agente muerto** | sin heartbeat en 3× `heartbeat_sec` | Su card se reasigna, su lease expira. |
+
+---
+
+## Arbitraje de los coordinadores
+
+```
+Pregunta de un especialista
+      |
+      ├─ ¿es de scope/objetivo/prioridad?   → COMANDANTE
+      ├─ ¿es de diseño/patrón/contrato?       → ARQUITECTO
+      ├─ ¿es de flujo/lease/gate/calidad?     → INTEGRADOR
+      |
+      └─ ¿cruza dos dominios?
+           → ARQUITECTO (decisión técnica) con visto bueno del COMANDANTE
+             si tiene impacto de scope; si el Integrador detecta deadlock
+             → INTEGRADOR reparte y avisa.
+```
+
+**Las preguntas al coordinador van por el bus**, no por chat. Un especialista nunca interrumpe al humano para preguntar algo que un coordinador puede resolver.
+
+Solo llega al humano si:
+- El coordinador no puede decidir (requiere criterio de producto/negocio)
+- Hay conflicto entre dominios que ningún coordinador resuelve
+- Se agotó el presupuesto o hay un bloqueo externo

package/skills/oficina/reference/protocol.md

@@ -0,0 +1,342 @@
+# Protocolo de OFICINA
+
+Este documento es la ley de la oficina. Si una regla acá y el criterio propio del agent discrepan, gana el criterio propio del agent — pero debe dejarlo escrito en el artefacto para que el Director pueda corregirlo.
+
+---
+
+## 0. PROJECT_ROOT y OFFICE_DIR
+
+Los permisos y las rutas relativas se resuelven contra el **directorio de trabajo de la sesión**, que no siempre es el proyecto. Antes de la primera card:
+
+1. Detectá `PROJECT_ROOT` buscando un marker de proyecto (`package.json`, `pyproject.toml`, `setup.py`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `Makefile`, `.git`) en el cwd, y si no hay, en los subdirectorios de primer nivel.
+2. `OFFICE_DIR = PROJECT_ROOT/.oficina/`. Si no se puede crear ahí, usá `~/.oficina/<slug>/`.
+3. **Todos los prompts de delegación llevan el PROJECT_ROOT absoluto.** Decí "todos los paths son relativos a `<PROJECT_ROOT>`" porque los subagentes heredan el cwd de la sesión.
+4. Anotá el PROJECT_ROOT y el OFFICE_DIR en `board.md` para que una sesión retomada los encuentre sin recalcular.
+
+### La oficina se vigila a sí misma
+
+El Verificador, en la fase 6 (diff review), además de buscar debug statements y archivos fuera de scope, **verifica que solo se haya tocado lo que la card autorizaba**. Si un agente modificó archivos fuera de su scope — incluido el Director tocando código de producción — eso es un finding y la card va a REWORK.
+
+La oficina no confía en la disciplina: la audita.
+
+---
+
+## 1. Ciclo de vida de una card
+
+```
+TODO ──(deps ok + agente asignado)──> IN_PROGRESS
+  │                                          │
+  │                                          ├──(owner entrega handoff + evidence)──> REVIEW
+  │                                          │                                          │
+  │                                          │                        ┌─────────────────���────┴──────────┐
+  │                                          │                        │  Crítico (≠ owner)              │
+  │                                          │                        │  APROBADO ─────────┐            │
+  │                                          │                        │  RECHAZADO ──┐     │            │
+  │                                          │                        └──────────────┼─────┘            │
+  │                                          │                                       │                  │
+  │                                          │                                 Verificador + Guardián
+  │                                          │                                       │
+  │                                          │                    ┌──────────────────┴───────────────┐
+  │                                          │                    │  PASS ────────────> DONE         │
+  │                                          │                    │  FAIL ──> REWORK ─┘                 │
+  │                                          │                                                  │
+  │                                          │   Rework 1 → vuelve a IN_PROGRESS (mismo owner, feedback)
+  │                                          │   Rework 2 → REPLAN (Director rehace la card, puede cambiar owner)
+  │                                          │   Rework 3 → ESCALATED (pide decisión al usuario)
+  └──────────────────────────────────────────┘
+```
+
+---
+
+## 2. Artefactos: la memoria de la oficina
+
+Una card vive en `.oficina/artifacts/<card-id>/`. Si no hay archivo, no hay hecho.
+
+### `handoff.md` (lo escribe el owner)
+
+```markdown
+# <card-id> — <título>
+
+**Owner:** <agente>
+**Estado:** IN_PROGRESS → REVIEW
+**Fecha:** <ISO>
+
+## Qué hice
+<qué se implementó, en concreto>
+
+## Archivos tocados
+- `path/to/file.ts` — <qué cambió y por qué>
+- `path/to/other.ts` — ...
+
+## Decisiones tomadas
+- <decisión> — <rationale>
+
+## Qué quedó afuera
+- <qué NO se hizo y por qué>
+
+## Qué necesita el siguiente
+- <lo que la siguiente card o el usuario debe saber>
+```
+
+### `evidence.md` (lo escribe el owner)
+
+Salida **real** de comandos. Sin cromo, sin "debería funcionar":
+
+```markdown
+# Evidencia — <card-id>
+
+## Comando: `npm test`
+```
+<salida real pegada>
+```
+**Resultado:** PASS (23 tests, 0 fail)
+```
+
+Regla: si no pegaste la salida real, la card no tiene evidencia y va a REWORK.
+
+### `review.md` (lo escribe el Crítico)
+
+```markdown
+# Revisión — <card-id>
+
+**Revisor:** <agente> (≠ owner)
+**Alcance:** <archivos exactos revisados>
+**Ledger:** <qué se leyó completo, callers leídos, paths compartidos trazados>
+
+## Veredicto: APROBADO | RECHAZADO
+
+## Findings
+
+### [C-001] <título>
+- **Confianza:** 92
+- **Ubicación:** `path/file.ts:42`
+- **Categoría:** Security
+- **Descripción:** <qué está mal>
+- **Escenario de reproducción:** <pasos concretos que lo disparan>
+- **Baseline:** <evidencia de que lo introdujo esta card>
+- **Fix:** <dirección>
+- **Test de regresión:** <dónde va>
+
+## Dimensiones revisadas
+- security: <sí/no — por qué>
+- performance: <sí/no — por qué>
+- architecture: <sí/no — por qué>
+- testing: <sí/no — por qué>
+```
+
+### `gates.md` (lo escriben Verificador y Guardián)
+
+```markdown
+# Gates — <card-id>
+
+## Técnico
+| # | Fase | Comando | Resultado | Detalle |
+|---|------|---------|-----------|---------|
+| 1 | Build | `npm run build` | PASS | exit 0 |
+| 2 | Type check | `tsc --noEmit` | PASS | 0 errores |
+| 3 | Lint | `eslint .` | FAIL | 3 warnings nuevos |
+| 4 | Tests | `npm test` | PASS | 23/23 |
+| 5 | Sec grep | `grep -rE "AKIA..."` | PASS | 0 |
+| 6 | Diff | `git diff main` | PASS | 4 archivos |
+
+**Gate técnico:** FAIL
+
+## Seguridad
+- Trust boundaries: <mapeadas>
+- Input paths auditados: <lista>
+- Secretos: <resultado del escaneo>
+- Dependencias: <resultado>
+- Findings de seguridad: <lista o "ninguno">
+
+**Gate seguridad:** PASS
+```
+
+### `decision.md` (lo escribe el Director)
+
+```markdown
+# Decisión — <card-id>
+
+**Decisión:** APROBADA | REWORK | REPLAN | ESCALADA
+**Razón:** <por qué>
+**Siguiente:** <qué card sigue, o qué se le pregunta al usuario>
+```
+
+---
+
+## 3. Handoff: cómo se coordinan sin hablar
+
+El problema: los subagentes son stateless. No se ven entre sí.
+
+La solución: **el disco es el bus de mensajes**.
+
+```
+Implementador  ──escribe──> artifacts/T-01/handoff.md
+                                      │
+                                      ▼
+Crítico         ──lee──────> artifacts/T-01/handoff.md + artifacts/T-00/handoff.md
+                        │
+                        ▼
+              artifacts/T-01/review.md
+                                      │
+                                      ▼
+Verificador     ──lee──────> artifacts/T-01/{handoff,evidence,review}.md
+                        │
+                        ▼
+              artifacts/T-01/gates.md
+                                      │
+                                      ▼
+Director         ──lee──────> artifacts/T-01/*.md → actualiza board.md + state.json
+```
+
+**Regla de lectura:** antes de empezar una card, el agente lee **todos** los `handoff.md` de cards previas que le importen + `context.md`. No pregunta, lee.
+
+**Regla de escritura:** cada agente deja su salida en su archivo. Nunca en el chat.
+
+### `.oficina/context.md` — el ledger acumulado
+
+```markdown
+# Contexto de la corrida — <objetivo>
+
+## Decisiones tomadas
+- [T-00] Usamos JWT con refresh tokens porque <razón> (decidido por code-architect)
+
+## Constraints descubiertos
+- [T-01] El proyecto usa Prisma, no SQL directo
+- [T-02] Los tests corren con `npm test` (no `npm run test:unit`)
+
+## Piezas construidas
+- [T-01] `src/auth/login.ts` — endpoint de login, retorna access + refresh
+- [T-02] `prisma/schema.prisma` — modelo User con email único
+
+## Trampas encontradas
+- [T-01] `src/lib/oldAuth.ts` está muerto, no borrar (lo usa `scripts/legacy-migrate.ts`)
+
+## Temas abiertos
+- Falta decidir rate limiting en login
+```
+
+Este archivo es **lo que evita la repetición**. El Director lo actualiza al cerrar cada card.
+
+---
+
+## 4. Gates de calidad (quality bar)
+
+De la skill `verification-loop`. El Verificador corre las 6 fases.
+
+**Reglas:**
+- Una fase aplicable en FAIL → la card va a REWORK.
+- Una fase no aplicable → `N/A` con el motivo explícito. Ej: "N/A — el proyecto no tiene type checker".
+- Gate técnico y gate seguridad son **independientes**: security PASS + tech FAIL = REWORK.
+- El Crítico y el Verificador son gates distintos. Reviewer ok + build roto = REWORK. Build ok + review con findings = REWORK.
+
+**Umbral de confianza de findings:** ≥ 80. Findings por debajo se descartan con la razón anotada (no se borran en silencio).
+
+---
+
+## 5. Escalamiento
+
+Escalar es caro. No hacerlo por todo. Reglas:
+
+| Situación | Acción |
+|---|---|
+| Card rechazada 1 vez | Rework automático. Sin escalar. |
+| Card rechazada 2 veces | **Replan**: el Director rehace la card — puede cambiar owner, scope, approach, o partirla en dos. Sin escalar. |
+| Card rechazada 3 veces | **ESCALAR**: se le presenta al usuario el objetivo de la card, los 3 intentos, por qué falló, y 2-3 opciones concretas con recomendación. |
+| Dependencia externa (API caída, credencial faltante, decisión de producto) | **ESCALAR** inmediatamente. No reintentar. |
+| Objetivo ambiguo con impacto grande en el diseño | **ESCALAR** antes de construir. |
+| Conflicto entre cards (mismo archivo, approaches incompatibles) | **ESCALAR**. |
+| Presupuesto de cards/agentes agotado | **ESCALAR** con informe de lo alcanzado. |
+
+**Formato de escalación:**
+
+```markdown
+## 🛑 Escalación — <card-id>
+
+**Objetivo de la card:** ...
+**Qué intenté:** 3 intentos (resumen de 1 línea cada uno)
+**Por qué no avanza:** <causa raíz>
+**Archivos en juego:** ...
+
+**Opción A:** <qué hacer> — <trade-off>
+**Opción B:** <qué hacer> — <trade-off>
+**Opción C:** <qué hacer> — <trade-off>
+
+**Mi recomendación:** <Opción X> porque <razón>
+```
+
+Nunca escalar con un monólogo. Siempre con opciones.
+
+---
+
+## 6. Checkpoints (control pane)
+
+Cada 3 cards completadas → informe al usuario:
+
+```markdown
+## 🏢 Checkpoint — <n>/<total> cards
+
+**Objetivo:** <objetivo original>
+**Progreso:** <n>/<total> cards DONE
+
+| Card | Estado | Owner | Gates | Revisión |
+|------|--------|-------|-------|----------|
+| T-00 | DONE | code-explorer | ✅ | APROBADO |
+| T-01 | IN_PROGRESS | general | — | — |
+| T-02 | BLOCKED | general | ❌ | RECHAZADO |
+
+**Bloqueos:** <ninguno | lista con owner y acción>
+**Siguiente:** <qué sigue>
+```
+
+El checkpoint **no pide permiso**. Informa y sigue. Solo frena si hay una escalación.
+
+---
+
+## 7. Informe final de entrega
+
+```markdown
+# 🏢 OFICINA — Informe de entrega
+
+**Objetivo:** <objetivo original>
+**Fecha:** <ISO>
+**Resultado:** CUMPLIDO | PARCIAL | BLOQUEADO
+
+## Trabajo entregado
+| Card | Qué entregó | Owner | Evidencia |
+|------|-------------|-------|-----------|
+| T-00 | Mapa de auth existente | code-explorer | artifacts/T-00/ |
+
+## Gates finales
+- Técnico: PASS/FAIL (<fases>)
+- Seguridad: PASS/FAIL (<hallazgos>)
+- Revisiones: <n> APROBADAS, <n> RECHAZADAS
+
+## Archivos tocados
+- <lista>
+
+## Decisiones clave
+- <decisión> — <razón>
+
+## Qué NO se hizo
+- <alcance excluido> — <por qué>
+
+## Deuda técnica dejada
+- <deuda> — <por qué se aceptó>
+
+## Recomendaciones
+- <qué haría distinto la próxima vez>
+```
+
+---
+
+## 8. Recuperación tras reinicio
+
+Si la sesión se corta a mitad de una corrida:
+
+1. Leer `.oficina/state.json` → obtener card actual, iteración, contadores
+2. Leer `.oficina/board.md` → ver el panorama
+3. Buscar artifacts de la card en curso: si hay `handoff.md` pero no `review.md` → la card está en REVIEW, delegar al Crítico
+4. Si no hay artifacts → la card está en IN_PROGRESS, reasignar al owner
+5. `context.md` mantiene el conocimiento acumulado
+
+**Nunca arranques de cero si existe `.oficina/`.**