@trycore/spec-build-harness 0.12.0 → 0.14.0

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.12.0",
+  "version": "0.14.0",
   "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/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

package/VERSION

@@ -1 +1 @@
-0.12.0
+0.14.0

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.
@@ -243,30 +268,47 @@ en el runtime. **Importarlo es un acto de gobierno**: la superficie exige sesió
 el token de agente. El arnés **prepara y valida**; una persona sube.
 
 1. Extrae el grafo de los artefactos de discovery ya leídos (`docs/03-backlog/epicas.md`,
-   `docs/02-user-story-map/`, `docs/04-historias/`) a un JSON:
+   `docs/02-user-story-map/`, `docs/04-historias/`) a un JSON. **Las dependencias las extrae
+   el script, no tú** (paso 2): puebla `depends_on` con lo que veas, pero **nunca lo dejes
+   vacío por defecto** — un grafo sin aristas no falla, solo empobrece el Lienzo en silencio
+   (issue #56: 41/41 épicas llegaron al hub con `depends_on: []`).
 
    ```json
    {"project_ref": "<nombre del proyecto>",
     "epics": [{"code": "EP-001", "title": "…", "layer": "foundational",
                "files_scope": ["src/core/**"], "depends_on": [],
-               "stories": [{"id": "HU-001", "title": "…"}]}],
-    "release_lines": [{"id": "R1-mvp", "epics": ["EP-001"]}]}
+               "stories": [{"id": "HU-001", "title": "…"}]},
+              {"code": "EP-002", "title": "…", "layer": "business",
+               "files_scope": ["src/pagos/**"], "depends_on": ["EP-001"],
+               "stories": [{"id": "HU-011", "title": "…"}]}],
+    "release_lines": [{"id": "R1-mvp", "epics": ["EP-001", "EP-002"]}]}
    ```
 
-2. Normalízalo y valídalo (determinista, nunca sube nada). La salida va a
-   `.claude/state/graph-bundle.json` para que `trycore-build migrate` la encuentre sola:
+2. Normalízalo y valídalo (determinista, nunca sube nada). **Pasa siempre `--from-docs`**: el
+   script relee el campo `**Depende de**` de cada sección de épica y **une** ese grafo al del
+   JSON — es la única lectura fiable de las dependencias, que la metodología escribe como
+   prosa. La salida va a `.claude/state/graph-bundle.json` para que `trycore-build migrate` la
+   encuentre sola:
 
    ```bash
-   python3 .claude/scripts/lib/graph-bundle.py < /tmp/epics.json > .claude/state/graph-bundle.json
+   python3 .claude/scripts/lib/graph-bundle.py --from-docs docs/03-backlog/epicas.md \
+     < /tmp/epics.json > .claude/state/graph-bundle.json
    ```
 
+   Para inspeccionar solo lo extraído (sin armar el bundle):
+   `python3 .claude/scripts/lib/graph-bundle.py --print-deps docs/03-backlog/epicas.md`.
+   Si una épica declara el campo estructurado `depende_de: [EP-001]`, ese gana sobre la prosa.
+
    El script emite las épicas en el **formato exacto del hub**: `layer` en MAYÚSCULA
    (`FOUNDATIONAL`|`BUSINESS` — un layer inválido rechaza el grafo ENTERO), historias con
    `code`, y `release_line` (string) por épica.
 
 3. **Lee los avisos** (`warnings` del bundle y stderr): capa ausente, dependencia inexistente,
-   ciclo, línea de release que referencia una épica desconocida. Corrígelos en discovery — el arnés
-   **no inventa** el grafo ni edita `epicas.md` (salvo el carve-out de la épica caparazón, Fase 2c).
+   ciclo, línea de release que referencia una épica desconocida, épica que está en los docs pero
+   no en tu JSON, épica sin campo `Depende de`. Contrasta la línea `info: … N aristas en el
+   grafo` con lo que declara el backlog: **0 aristas en un backlog con dependencias es el
+   síntoma de #56**. Corrígelos en discovery — el arnés **no inventa** el grafo ni edita
+   `epicas.md` (salvo el carve-out de la épica caparazón, Fase 2c).
 
 4. **Entrega al ADMIN un solo fichero.** Si vas a migrar historial, corre `trycore-build migrate`:
    embebe el grafo como sección `graph` del bundle de estado (un único fichero para la pantalla de

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/normalize.js

@@ -1118,6 +1118,17 @@ export function verifyNormalizedBundle(bundle) {
                 message: 'source_key debe tener entre 1 y 200 caracteres (LegacyImported, event_catalog.py:446)',
             });
         }
+        // ImportBundleIn tipa `original` como dict: un escalar responde 422
+        // `dict_type` en la validación pydantic y tumba el bundle ENTERO, antes de
+        // la persistencia por-entrada (issue #55). El bundle sale envuelto de
+        // `wireOriginal`; esto es la red que lo detecta en seco si alguien vuelve a
+        // emitir un escalar por otra vía.
+        if (typeof u.original !== 'object' || u.original === null || Array.isArray(u.original)) {
+            violations.push({
+                source_key: `unmapped[${i}]`,
+                message: 'original debe ser un objeto JSON: el hub lo tipa como dict y responde 422 dict_type sobre el bundle entero (ImportBundleIn)',
+            });
+        }
     });
     return violations;
 }

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/dist/lib/state-bundle.js

@@ -72,6 +72,20 @@ export function graphEpicsWithoutRepresentation(graph, representedCodes) {
         .map((e) => (typeof e.code === 'string' ? e.code : ''))
         .filter((code) => code !== '' && !represented.has(code));
 }
+/** El hub tipa `unmapped[].original` como dict (`ImportBundleIn`): un escalar
+ * responde 422 `dict_type` y tumba el bundle ENTERO en la validación pydantic,
+ * antes de la persistencia por-entrada — observado en el piloto con
+ * `facts[project_kind_source]: "auto"` (issue #55), pero lo emiten cuatro
+ * sitios (fact fuera de catálogo, elemento de history[] no-objeto, nota de
+ * release y `parallel_front.status: "closed"`). Los normalizadores conservan
+ * el valor legacy tal cual — la envoltura pertenece al cable y solo alcanza a
+ * lo que no es ya un objeto JSON, para no anidar dos veces lo que ya viaja bien. */
+function wireOriginal(entry) {
+    const { original } = entry;
+    if (typeof original === 'object' && original !== null && !Array.isArray(original))
+        return entry;
+    return { ...entry, original: { value: original } };
+}
 export function buildStateBundle(raw, projectRef, preHarness) {
     const warnings = [];
     const st = typeof raw === 'object' && raw !== null && !Array.isArray(raw) ? raw : {};
@@ -94,7 +108,7 @@ export function buildStateBundle(raw, projectRef, preHarness) {
     const fronts = front ? [front] : [];
     const factsUnmapped = [];
     const facts = normalizeFacts(st, EPOCH_ISO, warnings, factsUnmapped);
-    const unmapped = [...historyUnmapped, ...releasesUnmapped, ...frontUnmapped, ...factsUnmapped];
+    const unmapped = [...historyUnmapped, ...releasesUnmapped, ...frontUnmapped, ...factsUnmapped].map(wireOriginal);
     // Épicas pre-arnés (issue #42): lista CONFIRMADA por el humano — entrada
     // sintética archivada sin gates por épica (patrón del workaround del piloto).
     // Conflicto obvio ⇒ error, no fusión: una épica declarada pre-arnés que YA

package/docs/commands.md

@@ -129,7 +129,7 @@ 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.
@@ -139,6 +139,7 @@ protocolo del fichero (`/build:slice`) — no rompen el flujo normal si el proye
 | `/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: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/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)