@trycore/spec-build-harness 0.13.0 → 0.14.1

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "trycore-spec-build-harness",
   "displayName": "Trycore — Spec & Build Harness",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Arnés de construcción de dos loops (slice por épica + release gate) para Claude Code, con gates de calidad, estado compartido y OpenSpec. Compañero de @trycore/spec-product-flow. Agnóstico al proyecto.",
   "author": {
     "name": "Trycore",

package/INSTALL.md

@@ -19,6 +19,26 @@ Hay **dos canales** de instalación: el **CLI npm** (canónico, recomendado para
 proyecto) y el **plugin nativo** de Claude Code (conveniencia a nivel usuario). Lee el
 [caveat de canales](#5-alternativa-plugin-nativo-con-caveat-de-canales) antes de elegir.
 
+## ¿Qué camino me toca?
+
+Cuatro situaciones, cuatro caminos. Todos empiezan por §1 (CLI global) y §2 (requisitos).
+
+| Tu situación | Cómo saberlo | Qué haces |
+|---|---|---|
+| **Proyecto nuevo**, sin el arnés | no existe `.claude/.build-harness-version` | §3 `init` → §4 `/build:onboard`. Listo. |
+| **Proyecto existente** con el arnés, quieres ponerlo al día | existe la marca, con una versión vieja | §7 `update`. **No** re-corras `/build:onboard`: tu dominio ya está parametrizado. |
+| **Proyecto existente en `legacy`**, quieres conectarlo al IA Hub | existe la marca y `runtime.mode` es `legacy` | §7 `update` **primero**, luego §9 → [guía runtime §4](docs/runtime/guia-modo-dual-y-migracion.md) |
+| **Proyecto nuevo** que ya nace contra el IA Hub | — | §3 `init` **con las flags de runtime** (§9) → §4 `/build:onboard` |
+
+Dos cosas que ahorran disgustos:
+
+- **`init` y `update` son el mismo comando.** `init` detecta si ya hay instalación (por
+  `.claude/.build-harness-version`) y se comporta como `update`. Re-correrlo es seguro: **nunca**
+  pisa `build-state.json` ni `stack-allowlist.json`, que son del consumidor.
+- **Conectar un proyecto al hub exige el arnés al día primero.** Los hooks del cliente runtime no
+  existen antes de la 0.9.0: si escribes el modo sobre una instalación vieja, queda escrito y nada
+  lo ejecuta.
+
 ---
 
 ## 1. Instalar el CLI global (npm)
@@ -87,7 +107,7 @@ Qué hace `init`:
 1. **Verifica requisitos duros** (a menos que uses `--skip-doctor`).
 2. **Siembra los assets** en rutas nativas de Claude Code:
    - `.claude/agents/build/` — 14 agentes.
-   - `.claude/commands/opsx/` (10 comandos `/opsx:*`) y `.claude/commands/build/` (12 comandos: `/build:onboard`, `/build:reflect`, `/build:architect`, `/build:prototype`, `/build:slice`, `/build:release`, `/build:work`, `/build:resume`, `/build:front`, `/build:claim`, `/build:status`, `/build:escalate`).
+   - `.claude/commands/opsx/` (10 comandos `/opsx:*`) y `.claude/commands/build/` (13 comandos: `/build:onboard`, `/build:reflect`, `/build:architect`, `/build:prototype`, `/build:slice`, `/build:release`, `/build:work`, `/build:resume`, `/build:front`, `/build:claim`, `/build:status`, `/build:escalate`, `/build:epic`). Los cuatro últimos son la **superficie de agente del modo runtime** (§9): en `legacy`, `claim`, `escalate` y `epic` devuelven `rc 3` remitiendo al flujo del fichero, y `status` informa de que la fuente de verdad es `build-state.json`.
    - `.claude/skills/` — 16 skills (`building-a-slice`, `building-a-micro-change`, `releasing-a-version`, `managing-parallel-front`, `setup-architecture`, `prototyping-screens`, `openspec-*`).
    - `.claude/hooks/build/` — 19 hooks (bash + python; 6 son del cliente runtime opt-in — §9).
 3. **Siembra el estado**: `state/build-state.schema.json` y `state/README.md` se versionan;
@@ -166,9 +186,9 @@ Tras `init`, abre Claude Code en el proyecto y ejecuta:
 ```
 
 `/build:onboard` lee el PRD técnico (y `openspec/project.md` si existe) y, vía `AskUserQuestion`
-(proponiendo un valor "(Recomendado)" por punto), confirma y resuelve **6 puntos de extensión**
+(proponiendo un valor "(Recomendado)" por punto), confirma y resuelve **7 puntos de extensión**
 que leen los agentes de calidad (`security-reviewer`, `stack-guardian`, `data-consistency-checker`,
-`ux-krug-reviewer`, `simple-design-reviewer`):
+`ux-krug-reviewer`, `simple-design-reviewer`, `ux-fidelity-reviewer`):
 
 | Placeholder | Qué pregunta |
 |---|---|
@@ -178,6 +198,7 @@ que leen los agentes de calidad (`security-reviewer`, `stack-guardian`, `data-co
 | `{{SENSITIVE_DATA_CATEGORIES}}` | Categorías de datos sensibles / PII reguladas |
 | `{{SERVER_SIDE_SECRETS}}` | Secretos server-side que jamás van al cliente |
 | `{{HIGH_STAKES_DECISIONS}}` | Decisiones de alto impacto que exigen explicabilidad en la UI |
+| `{{DESIGN_SOURCE}}` | Fuente de diseño / referencia visual (prototipo, export), o `N/A` si el proyecto no tiene UI |
 
 Qué resuelve:
 
@@ -308,12 +329,44 @@ modo `legacy` (default, sin cambios). Requiere un runtime corriendo y un **token
 emitido por un ADMIN en la consola del hub.
 
 ```bash
+# Proyecto nuevo contra el hub, o proyecto existente YA actualizado (ver la tabla del principio)
 trycore-build init --runtime-url "https://tu-runtime.example.com" --runtime-token "<token>"
+
 trycore-build doctor    # sección "Runtime": token, conectividad, lock, cola offline
 trycore-build status    # sección "Runtime": conexión, proyección, contexto sincronizado
 trycore-build migrate --project-ref "<nombre-en-el-hub>"   # bundle de estado histórico para un ADMIN
 ```
 
+Sin `--runtime-mode`, el default con URL+token es **`dual`** (nunca `runtime`): el fichero local
+sigue mandando y cada transición se espeja al servidor para poder compararlas. El corte directo a
+`runtime` no está soportado por diseño.
+
+### Qué gana el proyecto al conectarse
+
+| | Qué hace | Necesita el hub |
+|---|---|---|
+| **Contexto vivo** | El daemon refresca `/agent/context` cada `runtime.context_refresh_s` segundos (default 45, `0` desactiva) — una terminal abierta se entera de lo que pasa sin reiniciar | **No**, funciona hoy |
+| **Épicas propuestas** | `/build:epic` propone la épica, el hub asigna el `EP-XXX` al aprobarla y `/build:epic --check` la proyecta a `epicas.md` | Sí (`trycore-ia-hub#113`/`#114`) |
+| **Versión de grafo** | `claim` y la propuesta mandan la versión conocida; un `409` provoca refresco y reintento en vez de fallo | Sí (`trycore-ia-hub#115`) |
+| **Reparto de trabajo** | `/build:claim` pide la siguiente tarea por lease; `/build:status` informa; `/build:escalate` registra un bloqueo | Sí |
+
+Contra un hub que no implementa una de esas mitades, el cliente **degrada limpiamente**: un `404`
+se aparta diciendo «esta instancia está sin soporte», sin reintentos en bucle, y un hub que no
+versiona el grafo ve el mismo cuerpo de `claim` de siempre.
+
+### Configuración
+
+`.claude/config/build-config.json`, bloque `runtime`:
+
+| Clave | Default | Para qué |
+|---|---|---|
+| `mode` | `legacy` | `legacy` \| `dual` \| `runtime`. Un valor inválido cae a `legacy`, nunca a la red. |
+| `stale_seconds` | `900` | A partir de cuántos segundos la proyección se considera stale |
+| `context_refresh_s` | `45` | Cadencia del refresco de contexto del daemon; `0` lo desactiva |
+
+Overrides por entorno, útiles para una sesión puntual sin editar el fichero:
+`TRYCORE_RUNTIME_MODE`, `TRYCORE_CONTEXT_REFRESH_S`.
+
 Guía completa (los tres modos, cómo activar/verificar/volver a legacy, cuándo se corta) →
 [`docs/runtime/guia-modo-dual-y-migracion.md`](docs/runtime/guia-modo-dual-y-migracion.md).
 

package/METODOLOGIA.md

@@ -542,7 +542,12 @@ al archivar (§6.4), el subárbol **`docs/adr/`** —propiedad de construcción
 arquitectura (§9.3), la **épica caparazón** en `docs/03-backlog/epicas.md` — únicamente esa épica,
 únicamente con **aprobación humana explícita** del borrador propuesto en `/build:onboard` Fase 2c
 (frontmatter `origin: harness-draft`); si el humano rechaza, la épica se crea en discovery como
-siempre —, y el subárbol **`docs/05-prototipo/`** —propiedad de construcción— donde
+siempre. En modo `runtime` ese carve-out cambia de forma: el arnés **no elige la identidad** —
+propone la épica al hub (`slice-ops.sh propose-epic`), un humano la aprueba y el fichero se
+escribe después como **proyección** del grafo, con el `EP-XXX` que asignó el hub
+(`origin: harness-writeback`, vía `/build:epic`). Es la misma frontera de escritura, con la
+numeración fuera de las manos del agente: elegir el código mirando el fichero es lo que hace que
+dos terminales colisionen —, y el subárbol **`docs/05-prototipo/`** —propiedad de construcción— donde
 `/build:prototype` (skill `prototyping-screens`) produce el prototipo HTML de referencia (la fuente
 de diseño): las pantallas nacen `borrador` y solo pasan a `aprobada` con aprobación humana, análogo
 a `docs/adr/`. Ni `docs/adr/` ni `docs/05-prototipo/` son artefactos de discovery: son salida de

package/README.md

@@ -79,6 +79,7 @@ Gate de release que corre **una sola vez por versión** sobre el conjunto de sli
 | `/build:work` | Router *classify-and-act*: clasifica el trabajo entrante y enruta al carril correcto (`building-a-micro-change` · `building-a-slice` · `releasing-a-version`). Es ruteo, no política: no ejecuta el pipeline ni toca el estado. |
 | `/build:resume` | Rehidrata el slice activo **desde disco** (no desde la conversación) tras un reinicio de contexto: reconcilia el estado, lee `session_continuity`/`wiring_checklist`/`parallel_front` y determina la siguiente acción por prioridad. |
 | `/build:front` | Abre y coordina un **front paralelo** de épicas no fundacionales y disjuntas en archivos (`parallel_front`), cada una en su worktree/rama/PR. Delega en la skill `managing-parallel-front`. |
+| `/build:epic` | Propone una **épica incremental** al hub (modo `runtime`): el agente redacta y propone, el hub asigna el `EP-XXX` al aprobar y un humano aprueba; después `epicas.md` se escribe como **proyección** del grafo. En `legacy`/`dual` no aplica. |
 | `/opsx:*` (10) | Ciclo OpenSpec: `explore` · `new` · `continue` · `apply` · `verify` · `archive` · `bulk-archive` · `ff` · `onboard` · `sync`. Detalle → [`docs/commands.md`](docs/commands.md). |
 
 ## Gestión de contexto
@@ -142,7 +143,7 @@ trycore-spec-build-harness/
 ├── agents/build/              ← 14 agentes revisores (segunda opinión, contexto limpio)
 ├── commands/
 │   ├── opsx/                  ← 10 comandos /opsx:* (ciclo OpenSpec)
-│   └── build/                 ← 12 comandos /build:* (onboard, reflect, architect, prototype, slice, release, work, resume, front, claim, status, escalate)
+│   └── build/                 ← 13 comandos /build:* (onboard, reflect, architect, prototype, slice, release, work, resume, front, claim, status, escalate, epic)
 ├── skills/                    ← 16 skills (building-a-slice, building-a-micro-change, releasing-a-version, managing-parallel-front, setup-architecture, prototyping-screens, 10 openspec-*) + 3 plantillas *.workflow.js (opt-in, read-only)
 ├── hooks/build/               ← 19 hooks (gate-check, reflect-nudge, release-gate-nudge, scaffold-guard, gitflow-guard, stack-guard, statusline-bridge, context-monitor, reconcile-build-state, …) + 6 opt-in del cliente runtime (session-start, event-emitter, context-sync, heartbeat, dual-compare, session-stop — ver docs/hooks.md)
 ├── state/                     ← máquina de estado legacy: build-state.json + schema + README
@@ -182,7 +183,50 @@ El core no menciona ningún dominio de cliente. Toda parametrización entra por
 
 ## Roadmap
 
-- ✅ **v0.10.0 (actual) — convergencia del inner loop** — ataque a los seis multiplicadores de
+- ✅ **v0.14.0 (actual) — contexto vivo, épicas propuestas y versión de grafo** (#61, #62, #63) —
+  tres capacidades del cliente del runtime que componen entre sí. **(1)** El daemon de heartbeat
+  refresca `GET /agent/context` con **cadencia propia** (`runtime.context_refresh_s`, default 45 s,
+  `0` la desactiva): antes la caché se hidrataba al arrancar la sesión y en cada `claim` —y el
+  `claim` ocurre una vez por slice—, así que una terminal abierta podía trabajar horas contra una
+  foto vieja; un refresco fallido **conserva** la caché anterior y la marca stale, porque quedarse
+  sin proyección dejaría al agente huérfano. **(2)** En modo `runtime` la épica se **propone** al
+  hub en vez de escribirse en el backlog: comando nuevo **`/build:epic`**, subcomandos
+  `propose-epic`/`epic-status`/`epic-writeback` y un **carril directo** en la cola offline que
+  sobrevive a quedarse sin red; el hub asigna el `EP-XXX` al aprobar y `docs/03-backlog/epicas.md`
+  pasa a ser **proyección del grafo**, nunca una fuente paralela —el agente pierde la potestad de
+  inventar identidades, que es lo que hacía colisionar las historias de dos épicas creadas el mismo
+  día—. **(3)** `claim` y la propuesta mandan la **versión de grafo** conocida, estampada *al
+  despachar* y no al encolar; un `409` por grafo rancio provoca refresco y un reintento en vez de
+  un fallo. `legacy` sigue siendo el default y no cambia. Las mitades de servidor de (2) y (3)
+  (`trycore-ia-hub#113`/`#114`/`#115`) están pendientes: contra un hub sin ellas el cliente degrada
+  a «instancia sin soporte». Total: **14 agentes**, **19 hooks**, **13 comandos `/build:*`**,
+  **16 skills**.
+- ✅ **v0.13.0 — el grafo llega al hub con aristas** — las dependencias entre épicas viven como
+  prosa en `epicas.md` (`**Depende de**: EP-001`) y su lectura estaba delegada al modelo, con un
+  ejemplo en `/build:onboard` que mostraba `"depends_on": []`: las 41 épicas del piloto entraron
+  sin una sola arista y nadie lo detectó, porque un grafo vacío no falla, solo empobrece (#56).
+  `graph-bundle.py` gana un **extractor determinista** (`--from-docs` / `--print-deps`) que relee
+  el campo, con avisos de cobertura y traza de la fuente en `depends_on_source`. Además,
+  `unmapped[].original` viaja siempre como dict (#55): el hub valida el bundle entero con pydantic,
+  así que un escalar lo rechazaba **completo** antes de persistir nada.
+- ✅ **v0.12.0 — la fase del slice llega al hub** (#52) — el hub modela la fase con eventos
+  `phase_advanced` de orden estricto y exige `phase == pr` para archivar, pero el cliente no emitía
+  ninguna: los slices quedaban «en construcción» con su PR ya mergeado. Subcomando
+  `slice-ops.sh phase <to>`, que emite la cadena que falte (idempotente, sin saltos), y **catch-up
+  automático** al archivar. Además, `outbox/rejected/` deja de ser invisible: la razón del rechazo
+  se persiste en el propio fichero y la muestran `slice-ops.sh status` y `trycore-build status`/`doctor`.
+- ✅ **v0.11.1 — auto-cierre de releases en verde** — el cierre manual de una release con 6/6 gates
+  PASS era control-teatro: el hub la cierra solo (`closed_by: AUTO_6_OF_6_PASS`) y los casos
+  degradados siguen siendo decisión humana. Arreglado también que `release-ops.sh verdict` devolvía
+  **422 en todo reporte** (faltaba el campo `verdict` en mayúsculas junto a `status`).
+- ✅ **v0.11.0 — drift cliente↔hub del primer piloto real** (#36–#44) — la primera migración contra
+  el hub en producción reveló un desajuste sistemático entre lo que el cliente emite y lo que el
+  hub valida: `claim` devolvía 422 en todo intento, la cola offline **nunca drenaba**, `fact`
+  emitía tipos fuera del catálogo, `claim --epic` se ignoraba en silencio y repartía otra épica, y
+  el import rechazaba 36 de 41 entradas del bundle histórico. Cada fix verificado contra el código
+  real del hub, con regresión anti-drift nueva que valida todo tipo encolable contra una réplica
+  literal de su catálogo.
+- ✅ **v0.10.0 — convergencia del inner loop** — ataque a los seis multiplicadores de
   latencia de la verificación adversarial (iniciativa #31, issues #25–#30) **sin bajar el rigor**:
   **re-verificación incremental** con `verified_at_sha` por item de `wiring_checklist[]` (las
   pasadas 2+ re-ejecutan O(items tocados), no O(items totales)); **condición de parada** del bucle

package/VERSION

@@ -1 +1 @@
-0.13.0
+0.14.1

package/agents/build/dor-dod-gatekeeper.md

@@ -46,9 +46,16 @@ cumplen; lista cada una con ✓/✗:
    `slice-ops.sh status`. Si el proyecto es `greenfield` con caparazón **requerida** y la épica
    evaluada es `layer: business`: exige la caparazón **completada** (su épica archivada y con la
    checklist evidenciada). Si no lo está,
-   **NO abras el slice**: instruye construir primero la épica caparazón (`foundation.epic`; si es
-   `null`, correr `/build:onboard` Fase 2c o crearla en discovery). Las épicas `layer: foundational`
-   no se bloquean por este criterio. Brownfield o `foundation.required !== true` → **N/A** (no
+   **NO abras el slice**: instruye construir primero la épica caparazón. Cuál es esa épica
+   depende del modo: en `legacy`/`dual` es `foundation.epic` de `build-state.json` y, si es
+   `null`, se define en `/build:onboard` Fase 2c o en discovery. En `runtime` **`foundation.epic`
+   no existe** —la proyección solo trae `foundation_done`, y la Fase 2c propone la épica al hub
+   sin código—, así que no lo pidas: comprueba con `slice-ops.sh epic-status` si hay una
+   propuesta ya `PROPOSED` y, si la hay, instruye consultar `/build:epic --check` y esperar la
+   aprobación, **no** repetir la Fase 2c; solo si no hay ninguna propuesta, Fase 2c o discovery.
+   Las épicas `layer: foundational`
+   no se bloquean por este criterio. Brownfield o caparazón no requerida (`foundation.required
+   !== true` en `legacy`/`dual`; `foundation_done: true` en `runtime`) → **N/A** (no
    bloquea, no preguntes). A diferencia del criterio 7, aquí NO evalúas arrastre: en greenfield
    el bloqueo es incondicional hasta que el cimiento exista archivado.
 8. **Tamaño acotado**: si la épica supera el umbral del gate de descomposición —heurística por defecto

package/commands/build/epic.md

@@ -0,0 +1,109 @@
+---
+name: "BUILD: Epic"
+description: Propone una épica nueva al hub (modo runtime) y, tras la aprobación humana, la escribe en docs/03-backlog/epicas.md con el código que asignó el hub. Con --check no propone nada: solo consulta el estado de las propuestas y proyecta las ya aprobadas. El agente NO inventa el EP-XXX. Adaptador delgado sobre slice-ops.sh propose-epic/epic-status/epic-writeback.
+category: Workflow
+tags: [build-harness, runtime, backlog, epicas, trycore]
+---
+
+# /build:epic — proponer una épica (la identidad la decide el hub)
+
+Carril de las épicas **incrementales de construcción**: las que nacen en una terminal con el
+proyecto ya registrado en el hub. La descomposición **inicial** del backlog sigue siendo de
+discovery (`/trycore:epicas`, `@trycore/spec-product-flow`) y entra al hub por el import masivo
+de admin — este comando no la sustituye.
+
+**Regla dura**: el agente **no elige** el `EP-XXX`. Lo asigna el hub al aprobar. Elegirlo mirando
+`epicas.md` es lo que hace que dos terminales creen la misma numeración y sus historias colisionen.
+
+**Entrada (opcional):** `--check`. Sin argumento, el comando **propone** una épica nueva.
+
+## Despacho por argumento (léelo antes que nada)
+
+El comando tiene **dos carriles** y no se recorren de arriba abajo:
+
+- **Con `--check`** → ve directo al **§0** y luego **salta al §3**. `--check` es una consulta de
+  **solo lectura** sobre propuestas que ya existen: **no redactes ningún borrador y no propongas
+  nada** (§1 y §2 no se ejecutan, ni siquiera "por si acaso"). Es el carril que invocan el DoR
+  (`references/dor.md`) y el `dor-dod-gatekeeper` para averiguar si la épica caparazón ya está
+  propuesta: si ahí se propusiera una épica, la comprobación crearía **una segunda propuesta de
+  la misma épica** — exactamente la colisión que este comando existe para impedir.
+- **Sin argumento** → §0 → §1 → §2. El §3 se recorre después, cuando el humano haya aprobado en
+  la consola del hub (normalmente en otra invocación, con `--check`).
+
+## 0. Precondición
+
+```bash
+bash .claude/hooks/build/slice-ops.sh mode
+```
+
+- `legacy` → **STOP**: no hay hub al que proponer. La épica se crea en discovery
+  (`/trycore:*`); si es la épica caparazón, por el carve-out de `/build:onboard` Fase 2c.
+- `dual` → **STOP** igual, pero por otra razón: aquí **sí hay hub**, y el fichero local es el
+  primario. El carril de propuesta solo opera en `runtime`; la épica se crea como en `legacy` y
+  llega al hub por el import de admin. No lo diagnostiques como un problema de conexión.
+- `runtime` → sigue.
+
+## 1. Redactar el borrador (con el usuario)
+
+Reúne del repo y de `docs/` lo necesario y **propón** al usuario, vía **AskUserQuestion**:
+título, objetivo, capa (`foundational` | `business` | `technical`), alcance de archivos y
+dependencias con épicas existentes. Las historias van con AC en Given/When/Then.
+
+No inventes la clasificación de capa ni las dependencias: derívalas del PRD / Story Map y
+confírmalas. Sin aprobación explícita del usuario, **no propongas nada**.
+
+Escribe el borrador en un fichero temporal (nunca por argv):
+
+```json
+{
+  "title": "…",
+  "objective": "…",
+  "layer": "business",
+  "files_scope": ["src/…/**"],
+  "depends_on": ["EP-012"],
+  "stories": [{"title": "…", "acceptance_criteria": "Dado … Cuando … Entonces …"}]
+}
+```
+
+## 2. Proponer
+
+```bash
+bash .claude/hooks/build/slice-ops.sh propose-epic --file /tmp/epica-borrador.json
+```
+
+| rc | Significado | Qué haces |
+|---|---|---|
+| `0` | Enviada; el hub devolvió el identificador de la propuesta | Dile al usuario que queda **pendiente de aprobación humana** en la consola del hub |
+| `5` | Encolada, aún sin entregar (sin conexión, o el daemon estaba drenando la cola en ese instante) | Igual, avisando de que se despachará sola y de que `epic-status` la sigue |
+| `6` | El hub la rechazó (o falta `project_id`) | Muestra la razón; **no** reintentes en bucle |
+| `2` | Borrador inválido | Corrige el campo que indica el mensaje y repite |
+| `3` | `legacy`/`dual` | Vuelve al paso 0 |
+
+**No escribas `docs/03-backlog/epicas.md` aquí.** El fichero es una proyección del grafo: se
+escribe cuando existe el código, y el código no existe hasta que un humano aprueba.
+
+## 3. Después de la aprobación — `/build:epic --check`
+
+**Aquí aterriza `--check`** (viniendo del despacho de arriba). Los dos comandos son mecánicos:
+uno consulta, el otro proyecta lo ya aprobado. Ninguno propone nada.
+
+```bash
+bash .claude/hooks/build/slice-ops.sh epic-status
+bash .claude/hooks/build/slice-ops.sh epic-writeback
+```
+
+`epic-status` resuelve el estado de cada propuesta (`QUEUED` · `PROPOSED` · `APPROVED` ·
+`REJECTED` · `FAILED`). `epic-writeback` escribe en `epicas.md` **solo** las `APPROVED` que
+falten, con el código del hub, y es idempotente (`rc 7` = nada pendiente).
+
+Tras escribir, revisa el bloque con el usuario y **no toques el código a mano**: si algo está
+mal, se corrige en el hub y se vuelve a proyectar.
+
+## Guardrails
+
+- El agente **propone**; la identidad la decide el hub y la aprobación es humana (gobierno,
+  METODOLOGIA §10 regla 8). Ni el modelo ni el arnés aprueban una épica.
+- Los códigos de HU los pone el hub si los devuelve; el arnés **nunca** los inventa.
+- El único fichero de `docs/` que este comando toca es `docs/03-backlog/epicas.md`, y solo con
+  un código ya asignado (carve-out de METODOLOGIA §9.2).
+- En `legacy`/`dual` el comando no hace nada: el backlog vive en el fichero.

package/commands/build/onboard.md

@@ -117,20 +117,45 @@ Si `project_kind !== "greenfield"`, salta esta fase (N/A total).
    - **Existe** → propónla al usuario y fija `foundation.epic`.
    - **No existe** → **borrador híbrido**: redacta la épica caparazón (título, objetivo, una HU
      por ítem `applies: true` con AC en Given/When/Then) y preséntala vía AskUserQuestion.
-     - **Aprueba** → escríbela en `docs/03-backlog/epicas.md` con frontmatter
-       `layer: foundational` y `origin: harness-draft`, y fija `foundation.epic`.
-       **Este es el ÚNICO caso en que el arnés escribe una épica** (carve-out de METODOLOGIA
-       §9.2: solo la épica caparazón, solo con aprobación explícita).
+     - **Aprueba**, y `slice-ops.sh mode` dice `legacy`/`dual` → escríbela en
+       `docs/03-backlog/epicas.md` con frontmatter `layer: foundational` y
+       `origin: harness-draft`, y fija `foundation.epic`. **Este es el ÚNICO caso en que el
+       arnés escribe una épica por decisión propia** (carve-out de METODOLOGIA §9.2: solo la
+       épica caparazón, solo con aprobación explícita).
+     - **Aprueba**, y el modo es `runtime` → **no escribas el fichero**: propón la épica al hub
+       (la identidad la asigna él, issue #62) y deja `foundation.epic: null` hasta que vuelva
+       con código:
+
+       ```bash
+       bash .claude/hooks/build/slice-ops.sh propose-epic --file /tmp/epica-caparazon.json
+       ```
+
+       Explica al usuario que la épica queda **pendiente de aprobación humana** en la consola
+       del hub y que, una vez aprobada, `/build:epic --check` la escribe en `epicas.md` con su
+       `EP-XXX`. El hecho de fundación se reporta igual en el paso 3 (`--epic` no viaja al hub).
      - **Rechaza** → **STOP** de la fase: deja `foundation.epic: null`, instruye crearla en
        discovery (`/trycore:*`) con la checklist como alcance. El gate del DoR bloqueará las
        épicas de negocio igual hasta que exista y se archive.
 3. **Reportar el hecho**: escribe la checklist podada en un fichero temporal
-   (`[{"id","applies","evidence":""}, …]`) y repórtala en una sola transición:
+   (`[{"id","applies","evidence":""}, …]`) y repórtala en una sola transición. El valor de
+   `--epic` depende de si ya tienes un `EP-XXX` real:
 
-   ```bash
-   bash .claude/hooks/build/slice-ops.sh fact foundation \
-     --required true --epic EP-XXX --checklist-file /tmp/foundation-checklist.json
-   ```
+   - **Existe / `legacy`/`dual` con épica ya escrita** → pasa el código real:
+
+     ```bash
+     bash .claude/hooks/build/slice-ops.sh fact foundation \
+       --required true --epic EP-XXX --checklist-file /tmp/foundation-checklist.json
+     ```
+
+   - **`runtime` con la propuesta aún sin aprobar** (`foundation.epic: null`) → **omite `--epic`
+     por completo**. No inventes un `EP-XXX` de relleno: el flag ni se valida ni viaja al hub
+     (`_fact_foundation` en `slice-ops.sh` lo acepta solo por compat local; el hub solo recibe
+     `--required`), así que no hay coste mecánico en omitirlo — y sí lo hay en escribir uno falso.
+
+     ```bash
+     bash .claude/hooks/build/slice-ops.sh fact foundation \
+       --required true --checklist-file /tmp/foundation-checklist.json
+     ```
 
    `--required false` cuando el humano podó todos los ítems (no hay caparazón exigible).
    En modo legacy (rc 3) se escribe en el fichero con su protocolo.

package/commands/build/slice.md

@@ -62,8 +62,10 @@ fichero en `legacy`):
 - **Caparazón (solo greenfield)**: si `project_kind` es `greenfield` y `foundation_done` es `false`, y
   la épica objetivo es `layer: business` → **STOP**: solo la épica caparazón u otra fundacional puede
   abrir. `status` no identifica **cuál** es la épica caparazón (eso vive hoy en el fichero legacy,
-  leído directo por `dor-dod-gatekeeper`); pregunta o consúltalo ahí. Lo valida en detalle el
-  `dor-dod-gatekeeper` (criterio 7-bis). Brownfield → N/A, no preguntes.
+  leído directo por `dor-dod-gatekeeper`); pregunta o consúltalo ahí. En modo `runtime` puede no
+  existir todavía porque la propuesta está **pendiente de aprobación del hub**
+  (`/build:epic --check` lo dice): entonces el STOP es **esperar**, y no volver a proponerla.
+  Lo valida en detalle el `dor-dod-gatekeeper` (criterio 7-bis). Brownfield → N/A, no preguntes.
 
 El hook `scaffold-guard.sh` respalda esto en tiempo real.
 

package/commands/build/work.md

@@ -33,8 +33,12 @@ Aplica las reglas en orden:
    `greenfield` y `foundation_done` es `false` → **enruta directo a construir la épica caparazón**
    por el carril **`building-a-slice`**. `status` no trae **cuál** es esa épica (`foundation.epic`
    vive hoy en el fichero legacy, leído directo por `dor-dod-gatekeeper`); si no la encuentras o
-   está sin definir, enruta a `/build:onboard` (Fase 2c) o a discovery para definirla. Ninguna épica de
-   negocio pasa por delante. Brownfield, o caparazón no requerida (`foundation_done` ya `true`) →
+   está sin definir, enruta a `/build:onboard` (Fase 2c) o a discovery para definirla — **salvo en
+   modo `runtime`**, donde `foundation.epic` sin definir puede ser una propuesta **pendiente de
+   aprobación del hub**, no un olvido: consulta antes `slice-ops.sh epic-status` (o
+   `/build:epic --check`) y, si ya hay una propuesta `PROPOSED`, el destino es **esperar la
+   aprobación**, no re-onboardear (re-correr la Fase 2c propondría una segunda vez la misma épica
+   caparazón, issue #62). Ninguna épica de negocio pasa por delante. Brownfield, o caparazón no requerida (`foundation_done` ya `true`) →
    esta regla es N/A.
    Esta regla gatea **aperturas de slice** (épicas): el carril de **mantenimiento**
    (`building-a-micro-change`, regla 1) no se bloquea — un typo/copy/config fix sigue su carril

package/config/build-config.template.json

@@ -7,6 +7,7 @@
   },
   "runtime": {
     "mode": "legacy",
-    "stale_seconds": 900
+    "stale_seconds": 900,
+    "context_refresh_s": 45
   }
 }

package/dist/commands/init.js

@@ -225,6 +225,19 @@ function syncGitignoreBlock(targetDir, mode) {
         '.claude/state/runtime-projection.json',
         '.claude/state/.runtime-http-status',
         '.claude/state/outbox/',
+        // [Ronda de arreglo 1, Minor 7 / #63] El ledger local de propuestas de épica y el
+        // marcador de desfase de grafo son estado derivado del hub, igual que los de arriba —
+        // sin esto, un consumidor los commitea por descuido.
+        '.claude/state/epic-proposals.json',
+        '.claude/state/graph-status.json',
+        // [Ronda final · C5] Estado del daemon de heartbeat (EP-OR-08-B): un pid y unos ppids
+        // solo significan algo en LA máquina que los escribió. Commiteados, otro clon recibe un
+        // pidfile ajeno que el relanzamiento da por bueno hasta el `kill -0`, y un
+        // `heartbeat-status.json` con el lease de otro. Hueco preexistente, cerrado aquí porque
+        // esta rama ya edita este bloque.
+        '.claude/state/heartbeat.pid',
+        '.claude/state/heartbeat-sessions.json',
+        '.claude/state/heartbeat-status.json',
     ];
     if (mode === 'symlink') {
         // Los symlinks absolutos a node_modules global se rompen en otra máquina si se commitean.

package/dist/commands/status.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { readPackageVersion, targetPaths, PACKAGE_ROOT } from '../lib/paths.js';
 import { countChildren } from '../lib/install-engine.js';
 import { hasBinary } from './doctor.js';
-import { runtimeMode, getAgentContext, readProjection, readLock, rejectedStats } from '../lib/runtime-client.js';
+import { runtimeMode, getAgentContext, readProjection, readLock, rejectedStats, readGraphStatus } from '../lib/runtime-client.js';
 export async function status(opts) {
     const targetDir = path.resolve(opts.targetDir);
     const t = targetPaths(targetDir);
@@ -45,6 +45,18 @@ export async function status(opts) {
         if (proj.fetched_at) {
             const ageS = Math.max(0, Math.floor((Date.now() - Date.parse(String(proj.fetched_at))) / 1000));
             console.log(`  Proyección:   ✓ v${proj.context?.version ?? '?'} (hace ${ageS}s${ageS > 900 ? ' — ⚠ stale' : ''})`);
+            // [#63] La versión de grafo solo se muestra si el hub la expone: una instancia que no
+            // versiona no debe aparentar que sí.
+            const graphVersion = proj.context?.graph_version;
+            if (typeof graphVersion === 'number') {
+                // [Ronda de arreglo 1, Minor 5] El CHANGELOG dice que este comando avisa del desfase,
+                // no solo `slice-ops.sh status` — mismo criterio que el bash (Important 3): «servidor
+                // MAYOR que local», nunca `!==`, para no acusar desfase con un marcador de grafo viejo
+                // que apunta a una versión que la proyección ya superó.
+                const gs = readGraphStatus(targetDir);
+                const behind = typeof gs.server === 'number' && gs.server > graphVersion;
+                console.log(`  Grafo:        v${String(graphVersion)}${behind ? `  ⚠ por detrás del hub (v${gs.server}): refresca antes de reclamar o proponer` : ''}`);
+            }
             const slice = proj.active_slice;
             if (slice) {
                 console.log(`  Slice activo: ${slice.epic_code ?? '?'} (fase ${slice.phase ?? '?'})`);

package/dist/lib/paths.js

@@ -69,6 +69,7 @@ export function targetPaths(targetDir) {
         runtimeCredentialsFile: path.join(claudeDir, 'state', 'runtime.credentials'),
         runtimeLockFile: path.join(claudeDir, 'state', 'context.lock'),
         runtimeProjectionFile: path.join(claudeDir, 'state', 'runtime-projection.json'),
+        graphStatusFile: path.join(claudeDir, 'state', 'graph-status.json'),
         outboxDir: path.join(claudeDir, 'state', 'outbox'),
         settingsFile: path.join(claudeDir, 'settings.json'),
         versionFile: path.join(claudeDir, '.build-harness-version'),

package/dist/lib/runtime-client.js

@@ -11,6 +11,7 @@ function runtimePaths(targetDir) {
         credentials: t.runtimeCredentialsFile,
         lock: t.runtimeLockFile,
         projection: t.runtimeProjectionFile,
+        graphStatus: t.graphStatusFile,
         outboxDir: t.outboxDir,
         buildConfigFile: t.buildConfigFile,
     };
@@ -161,6 +162,25 @@ export function readLock(targetDir) {
         return { manifestHash: null, syncedAt: null, fileCount: 0 };
     }
 }
+/**
+ * Lectura fail-open del marcador de desfase de grafo (.claude/state/graph-status.json),
+ * escrito por `runtime_graph_note_stale` (hooks/build/lib/runtime-client.sh) cuando el hub
+ * rechaza `claim` o una propuesta con `409 stale_graph` [#63]. Sin fichero (nunca hubo
+ * desfase) o con JSON ilegible, ambos campos quedan `null` — nunca lanza.
+ */
+export function readGraphStatus(targetDir) {
+    const p = runtimePaths(targetDir).graphStatus;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(p, 'utf8'));
+        return {
+            local: typeof parsed?.local === 'number' ? parsed.local : null,
+            server: typeof parsed?.server === 'number' ? parsed.server : null,
+        };
+    }
+    catch {
+        return { local: null, server: null };
+    }
+}
 /** Estadísticas fail-open de la cola offline (.claude/state/outbox/*.json, sin dotfiles). */
 export function outboxStats(targetDir) {
     const dir = runtimePaths(targetDir).outboxDir;

package/docs/commands.md

@@ -129,16 +129,17 @@ El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y
 |---|---|
 | `/build:prototype` | Genera o amplía el **prototipo HTML de referencia** (el `DESIGN_SOURCE`) en `docs/05-prototipo/` (`DESIGN.md` + `tokens.css` + `manifest.json` + un HTML autocontenido por pantalla). Adaptador delgado: **delega** en la skill `prototyping-screens`. Dos modos — **greenfield** (`/build:prototype`): inventario de pantallas desde PRD/mapa/historias → confirmación humana → dirección estética (manual de marca o 2-3 variantes a elección humana) → generación por lotes con auto-verificación visual; **feature** (`/build:prototype <épica>`): pantallas nuevas coherentes con el UX/UI **ya implementado**, con **precondición dura** (app corriendo + MCP de inspección de UI: extrae CSS computado real, screenshots en 3 viewports y estructura; sin degradación estática). Es **outer-loop** (antes de abrir slices). **La skill genera; el humano aprueba**: las pantallas nacen `borrador`, solo las `aprobada` son fuente de verdad (las lee `ux-fidelity-reviewer` vía `manifest.json`) y `design_source.confirmed` sigue siendo humano. |
 
-### `/build:claim`, `/build:status`, `/build:escalate` — superficie de agente del runtime (beta, opt-in)
+### `/build:claim`, `/build:status`, `/build:escalate`, `/build:epic` — superficie de agente del runtime (beta, opt-in)
 
 Adaptadores delgados sobre `slice-ops.sh`; en modo `legacy` (default) devuelven `rc 3` y remiten al
 protocolo del fichero (`/build:slice`) — no rompen el flujo normal si el proyecto no está migrado.
 
 | Slash command | Propósito |
 |---|---|
-| `/build:claim [EP-XXX]` | Pide la siguiente tarea al runtime (`POST /tasks/next`): sincroniza contexto, reporta hashes locales (detección de drift) y reclama por lease. Si trae `CHECKPOINT`, continúa desde ahí — **nunca reinicia** un slice de otro agente. |
+| `/build:claim` | Pide la siguiente tarea al runtime (`POST /tasks/next`): sincroniza contexto, reporta hashes locales (detección de drift) y reclama por lease. Si trae `CHECKPOINT`, continúa desde ahí — **nunca reinicia** un slice de otro agente. **No acepta épica dirigida**: el hub reparte por orden de cola y `claim --epic` falla explícito con `rc 2` (issue #39 — el servidor ignoraba el `epic_code` y entregaba otra épica como si fuera la pedida, dejando un lease huérfano). |
 | `/build:status` | Informe de solo lectura: modo, slice activo, gates, wiring failing, versión de contexto, lease y cola de eventos pendientes. Nunca transiciona nada. |
 | `/build:escalate <razón>` | Registra un bloqueo en el runtime (`escalation_raised`) y devuelve la decisión a un humano — recortar, diferir o desbloquear **nunca** lo decide el modelo (mismo principio que la regla 8 de METODOLOGIA §10). |
+| `/build:epic` | Propone una épica **incremental de construcción** al hub y, tras la aprobación humana, la escribe en `docs/03-backlog/epicas.md` con el `EP-XXX` que asignó el hub (`/build:epic --check`). El agente **no elige** el código: elegirlo mirando el fichero es lo que hace colisionar a dos terminales. La descomposición inicial del backlog sigue siendo de discovery. |
 
 ---
 

package/docs/getting-started.md

@@ -24,6 +24,14 @@ trycore-build doctor     # verifica requisitos y hooks
 
 Eso es el ciclo completo. Lo de abajo explica cada paso.
 
+> **¿Conectado a un IA Hub?** El pipeline es **el mismo**; cambia dónde vive el estado y quién
+> valida las transiciones. Añades cuatro comandos a la caja de herramientas — `/build:claim` (pide
+> trabajo), `/build:status` (informe), `/build:epic` (propone una épica) y `/build:escalate`
+> (registra un bloqueo) — y el arranque lleva las flags de runtime. En `legacy` no estorban:
+> `claim`, `epic` y `escalate` devuelven `rc 3` y te remiten al flujo del fichero, y `status`
+> informa de que la fuente de verdad es `build-state.json`.
+> Instalación y activación → [`docs/runtime/guia-modo-dual-y-migracion.md`](runtime/guia-modo-dual-y-migracion.md).
+
 ---
 
 ## Requisitos duros
@@ -48,7 +56,9 @@ npm i -g @fission-ai/openspec @trycore/spec-build-harness
 
 ## 2 · `trycore-build init` (terminal)
 
-Desde la raíz de tu proyecto. Es **idempotente** (re-correrlo es seguro) y siembra: **14 agentes**, **16 skills** (`building-a-slice`, `building-a-micro-change`, `releasing-a-version`, `managing-parallel-front`, `setup-architecture`, `prototyping-screens` + 10 `openspec-*`), **10 comandos `/opsx:*`** + **9 comandos `/build:*`** (`onboard`, `reflect`, `architect`, `prototype`, `slice`, `release`, `work`, `resume`, `front`), **13 hooks**, el estado vacío `.claude/state/build-state.json` (gitignored, nunca se sobreescribe) y el bloque `<!-- BEGIN trycore-build-harness -->` en tu `CLAUDE.md` con `{{placeholders}}` sin resolver.
+Desde la raíz de tu proyecto. Es **idempotente** (re-correrlo es seguro) y siembra: **14 agentes**, **16 skills** (`building-a-slice`, `building-a-micro-change`, `releasing-a-version`, `managing-parallel-front`, `setup-architecture`, `prototyping-screens` + 10 `openspec-*`), **10 comandos `/opsx:*`** + **13 comandos `/build:*`** (`onboard`, `reflect`, `architect`, `prototype`, `slice`, `release`, `work`, `resume`, `front` + `claim`, `status`, `escalate`, `epic`, que son la superficie del modo runtime), **19 hooks**, el estado vacío `.claude/state/build-state.json` (gitignored, nunca se sobreescribe) y el bloque `<!-- BEGIN trycore-build-harness -->` en tu `CLAUDE.md` con `{{placeholders}}` sin resolver.
+
+> **¿Ya tenías el arnés instalado?** Entonces esto es un `update`, no un `init` — el CLI lo detecta solo por `.claude/.build-harness-version`. Corre `npm i -g @trycore/spec-build-harness@latest` y luego `trycore-build update`; **no** repitas `/build:onboard`, tu dominio ya está parametrizado. La tabla «¿Qué camino me toca?» de [`INSTALL.md`](../INSTALL.md) cubre los cuatro casos.
 
 ```bash
 trycore-build init

package/docs/hooks.md

@@ -35,7 +35,7 @@ Los hooks son el sistema nervioso del arnés: vigilan GitFlow, el stack declarad
 | `dual-compare.sh` | `Stop` | `.*` | (Beta, solo modo `dual`.) Detecta cuando la proyección del runtime diverge del fichero local (épica/fase/gates ya resueltos) y escala vía el mismo canal que `/build:escalate`. Es el instrumento de medición del piloto que condiciona el corte a `runtime` — nunca bloquea el cierre de sesión. | No |
 | `session-stop.sh` | `Stop` | `.*` | (Beta.) Deja `outbox/.flush-request` y asegura el daemon `heartbeat.sh` — el flush de la cola offline lo ejecuta el daemon, no el hook. No-op en `legacy`. | No |
 | `context-sync.sh` | invocado por `session-start.sh` y, pre-claim, por las skills (no registrado como hook) | — | (Beta.) Sincronización de contexto *content-addressed*: compara el `manifest_hash` esperado contra el lock local; si difiere, descarga solo los archivos gobernados (`config/`, `rules/`, `docs-cache/`) que cambiaron, por hash. Nunca escribe fuera de esos prefijos. Fail-open: sin runtime, sin `python3` o con manifiesto ilegible, deja el lock anterior intacto. | No |
-| `heartbeat.sh` | daemon singleton por repo, lanzado por `session-start.sh` (no registrado como hook) | — | (Beta.) Renueva el lease (`PUT /leases/renew`) y despacha la cola offline mientras viva al menos una sesión interesada (`.claude/state/heartbeat-sessions.json`). No existe evento Timer en Claude Code; por eso el latido es un daemon, no un hook. |
+| `heartbeat.sh` | daemon singleton por repo, lanzado por `session-start.sh` (no registrado como hook) | — | (Beta.) Renueva el lease (`PUT /leases/renew`), **refresca la caché de proyección desde `GET /agent/context` con su propia cadencia** (`runtime.context_refresh_s`, default 45 s; solo en modo `runtime`) y despacha la cola offline mientras viva al menos una sesión interesada (`.claude/state/heartbeat-sessions.json`). No existe evento Timer en Claude Code; por eso el latido es un daemon, no un hook. |
 
 > Cuatro bloqueantes (`gitflow-guard`, `stack-guard`, `scaffold-guard`, `design-source-guard`) y quince informativos. Los bloqueantes usan `exit 2`: Claude Code devuelve el `stderr` al modelo y aborta la herramienta; el resto siempre sale `0`. Los 4 bloqueantes **nunca** tocan la red (ni en `legacy` ni en `dual`/`runtime`) — ratchet estático en `scripts/tests/test-hooks-runtime.sh`.
 >
@@ -193,6 +193,16 @@ tick (`TRYCORE_HEARTBEAT_TICK_S`, default 5s): consume `outbox/.flush-request` y
 cada `lease_ttl_s/3` (mínimo 10s), `PUT /leases/renew`. **Sin lease no se apaga**: los eventos de
 ámbito proyecto (pre-claim) necesitan despachador igual.
 
+**Refresco de contexto (#61)**. Cada `runtime.context_refresh_s` segundos (default 45; `0` lo
+desactiva; override por `TRYCORE_CONTEXT_REFRESH_S`) el daemon hace `GET /agent/context` y
+reescribe la caché de proyección. Es la única vía por la que una terminal **abierta** se entera
+de algo nuevo: `session-start.sh` hidrata una vez y `slice-ops.sh` solo en `claim`/`status`, y el
+`claim` ocurre una vez por slice. La cadencia es propia y **no** el tick de 5 s: renovar un lease
+es barato, pedir la proyección entera del proyecto no. Si el refresco falla, la caché anterior
+queda **intacta** y se marca `context_stale: true` en `heartbeat-status.json` (lo muestra
+`slice-ops.sh status`): quedarse sin proyección convertiría al agente en huérfano, que es
+justo lo que arregla el PR #60. Solo corre en modo `runtime`.
+
 ---
 
 ## La cadena de comando única (sin doble disparo entre canales)