@trycore/spec-build-harness 0.13.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.13.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.13.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.

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,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)

package/docs/runtime/protocolo-cliente-runtime.md

@@ -59,6 +59,15 @@ Reglas del cliente (las implementa `slice-ops.sh claim`, no la prosa de la skill
    (rc 2, sin abrir socket) explicando el protocolo real: terminar el slice en dual → cutover
    admin → reclamar del hub lo que la cola reparta.
 
+**Versión de grafo (#63 / hub#115).** `GET /agent/context` expone `context.graph_version`; el
+cliente la manda en `POST /tasks/next` y en la propuesta de épica **solo si la conoce** (un hub
+que no versiona ve el cuerpo de siempre). Un `409` con `{"reason":"stale_graph","graph_version":
+M}` no es un error: se anota el desfase en `.claude/state/graph-status.json`, se refresca la
+proyección y se reintenta **una vez**; un segundo rechazo sale con un mensaje que nombra el
+desfase y la acción. En el carril directo la versión se estampa **al despachar**, nunca al
+encolar — sellarla al encolar condenaría al 409 a todo despacho diferido —, y tras tres
+rechazos consecutivos la petición se aparta en vez de reintentarse en bucle.
+
 Actos de dominio posteriores (todos por `slice-ops.sh`, ninguno a mano):
 `POST /slices/{id}/verdicts` · `POST /checkpoints` · `POST /slices/{id}/submit` · eventos
 `wiring_*`, `progress_noted`, `slice_archived`, `slice_escalated` y los hechos de
@@ -102,6 +111,32 @@ Offline: sin runtime se trabaja con el último lock; la statusline marca `⚠ st
 - Cota: 5 MB / 72 h — al superarla se descartan primero los eventos evictables (todo tipo fuera de la lista protegida), **nunca** `checkpoint_recorded`, `gate_verdict`, `slice_escalated`, `slice_submitted`, `slice_archived`, `wiring_*`, `project_fact_updated`, `handoff_recorded` ni el propio `telemetry_gap` (nombres del catálogo v2; los alias 0.10.x de los cuatro renombrados siguen protegidos porque la capa de compat los entrega). El descarte se reporta como evento `telemetry_gap` con el payload del catálogo `{dropped, window_h, reason}` (issue #44), coalescido en un único gap mientras la cola siga sobre la cota.
 - Flush forzado en `Stop`: `session-stop.sh` deja el sentinela `outbox/.flush-request`; el daemon `heartbeat.sh` lo consume de forma asíncrona (nunca en el hilo del hook). `trycore-build doctor` **reporta** el tamaño/edad de la cola pero **no** dispara un flush síncrono — sigue sin implementar.
 
+**Carril directo** (`channel: "direct"`). Un fichero de la outbox puede llevar `channel:
+"direct"`, `method` y `path`: entonces no entra en el lote de `POST /events`, se despacha solo a
+su endpoint. Comparte directorio, formato, cota (`RUNTIME_OUTBOX_PROTECTED`) y sentinela de
+flush con la cola de eventos.
+
+**Idempotencia del carril directo — contrato asumido de hub#113.** El cuerpo de cada petición
+del carril directo lleva `client_event_id` (el mismo UUID que nombra el fichero de la outbox) como
+**clave de idempotencia**: el servidor debe tratar dos peticiones con el mismo `client_event_id`
+como **una sola** y devolver el mismo recurso en la segunda, igual que hace `POST /events` con los
+`duplicates[]`. No es opcional. Hay **dos despachadores** posibles sobre la misma cola —el daemon
+de heartbeat y el proceso en primer plano de la skill (`slice-ops.sh propose-epic`)—; el cliente
+los serializa con un mutex de directorio (`.claude/state/.outbox-dispatch.lock`, `mkdir` atómico,
+liberación por edad a los 2 min), pero el mutex es **por repo**: dos worktrees del mismo proyecto,
+o un reintento tras un corte a mitad de respuesta, siguen pudiendo entregar la misma propuesta dos
+veces. Sin deduplicación server-side eso son **dos propuestas** y, al aprobarlas, **dos `EP-XXX`**
+para la misma épica — justo la colisión de numeración que el carril existe para evitar. Un
+`client_event_id` ya presente en el payload del productor **manda** (no se sobrescribe); el resto
+del cuerpo no se toca.
+
+Resultado por petición: `2xx` → acuse en `outbox/acks/<cid>.json`
+y borrado; `404` → **instancia del hub sin soporte**, se aparta a `rejected/` diciéndolo;
+`4xx` (salvo `408`/`429`) → rechazo de contrato, se aparta; `000`/`5xx`/`408`/`429` → se
+conserva y se reintenta en el siguiente ciclo. No agenda backoff propio: es de volumen
+bajísimo y compartir el del lote dejaría los hechos de dominio esperando detrás. La ruta la
+estampa `lib/runtime-ops.sh` al encolar — `runtime-client.sh` no conoce la tabla de endpoints.
+
 ## 6. Declaración de tipos de asset (`asset-types.json` del paquete)
 
 El paquete del plugin declara los tipos de documento que sabe generar. En el registro, el runtime hace upsert idempotente (aditivos auto-publicados; breaking quedan propuestos para un ADMIN):
@@ -146,6 +181,7 @@ agente jamás publica contexto.**
 | `422` (evento/veredicto rechazado por transición ilegal o schema) | **No reintentar**: mostrar la razón del servidor al modelo/usuario (compuerta mecánica funcionando); registrar localmente. |
 | Timeout/red caída | Modo offline (§4/§5); jamás bloquear PreToolUse ni el trabajo local. |
 | `409` en el renew de lease (`PUT /leases/renew`) | **No existe 410**: el servidor responde siempre `409` de cuerpo único (anti-oráculo). El daemon marca `lease_lost` en `.claude/state/heartbeat-status.json`, **no se apaga** (sigue despachando la cola) y la statusline muestra `⚠ lease`. La skill detiene el trabajo, hace checkpoint local y vuelve a reclamar. |
+| `409` `stale_graph` en `tasks/next` o en la propuesta | Grafo local rancio: anotar desfase, refrescar y reintentar **una vez**; segundo rechazo → `rc 6` con el desfase nombrado. En la cola: conservar y re-estampar con la versión del momento; se aparta al **tercer rechazo contra la MISMA versión local estampada** (si la versión cambió entre medias, hubo refresco de verdad y la racha vuelve a cero). El contador va con su versión (`graph_409`, `graph_409_at_version`) dentro del fichero de la outbox: contar rechazos a secas agotaría las tres vidas de la propuesta sin que hubiera ocurrido ni un refresco, porque el despacho corre en cada `Stop` mientras el refresco de contexto va a `runtime.context_refresh_s` (45 s, y `0` lo **desactiva**). |
 | Reloj local desviado | El cliente usa siempre `expires_at` del servidor, nunca calcula TTL con reloj propio. |
 
 ## 8. Seguridad del cliente
@@ -163,6 +199,13 @@ No existe evento Timer, los hooks son efímeros y un `PostToolUse` throttled no
 - **Muerte**: cuando no queda **ningún** ppid registrado vivo (dos sesiones sobre el mismo repo comparten daemon; cerrar la primera no lo mata). Nunca se cuelga de `Stop` ni de `SessionEnd`.
 - **Deberes por tick** (`TRYCORE_HEARTBEAT_TICK_S`, default 5 s): consumir `outbox/.flush-request` y despachar; cada `lease_ttl_s/3` (valor del servidor, mínimo 10 s), `PUT /leases/renew`. **Sin lease no se apaga**: los eventos de ámbito proyecto (pre-claim) necesitan despachador.
 
+**Deberes por tick** (cadencias independientes): consumir el sentinela de flush y despachar la
+cola; cada `lease_ttl_s/3`, renovar el lease; cada `runtime.context_refresh_s` (default 45 s),
+`GET /agent/context` para refrescar la proyección local. El refresco de contexto es la
+contrapartida cliente de los `nudges` del servidor: el hub ya los emite y el cliente ya los
+normaliza y los pinta — lo que faltaba era que alguien leyera con regularidad. Un refresco
+fallido nunca degrada la caché: se conserva la anterior y se marca `context_stale`.
+
 ## 10. Operaciones de skill (`slice-ops.sh` / `release-ops.sh`)
 
 Las skills son prosa: **no** arman peticiones. Cada acto de dominio pasa por un ejecutable
@@ -185,10 +228,31 @@ modo, valida en local lo que es barato validar y encola lo que no pudo entregar.
 | `slice-ops.sh propose-asset` | `POST …/context/agent-proposals` (§6) |
 | `slice-ops.sh status` | `GET /agent/context` (refresco) + ficheros locales; reporta además `outbox/rejected/` (conteo + tipo y razón del rechazo más reciente, issue #52) |
 | `slice-ops.sh escalate` | evento `slice_escalated {cause}` (gate y fase dentro del texto de la causa; exige slice activo en runtime) |
+| `slice-ops.sh propose-epic --file B` | `POST /projects/{id}/epic-proposals` (carril directo). Propone una épica **sin `EP-XXX`**: la identidad la asigna el hub al aprobar (hub#113). `0` enviada · `5` encolada · `6` rechazada · `3` legacy/dual. Un `epic_code` en el borrador se **ignora**, no se rechaza |
+| `slice-ops.sh epic-status [--id P]` | `GET /projects/{id}/epic-proposals/{P}`. Resuelve el ciclo: `QUEUED` → `PROPOSED` → `APPROVED` (con `epic_code`) / `REJECTED`. Informativo: `rc 0` siempre en runtime |
+| `slice-ops.sh epic-writeback [--id P] [--file F]` | — (local). Escribe en `docs/03-backlog/epicas.md` las épicas ya `APPROVED`, con el código del hub. Mecánico e idempotente: el fichero es proyección del grafo. `--file F` permite otro fichero del backlog (partido en varios), pero **F queda acotado al subárbol `docs/03-backlog/` del proyecto** —`realpath` sobre ambos lados, así que ni symlinks ni `..` escapan— porque los contactos de escritura del arnés en `docs/` son cuatro y acotados (METODOLOGIA §9.2) y este comando promete tocar solo el backlog. Fuera de ahí, `2` con la ruta permitida en el mensaje y **cero escritura**, exista el fichero o no. `0` escribió · `7` nada pendiente · `4` sin fichero · `2` `--file` fuera del carve-out |
 | `release-ops.sh verdict <line> <gate> <estado>` | `POST /releases/{line}/verdicts`; **sin fallback offline** (rc 5 y reintento al reconectar: el agregado `release` no entra por `POST /events`, issue #44) |
 | `release-ops.sh close-hint <line>` | **ninguna**: el cierre es humano, con PDP |
 | `release-ops.sh front-integration <front>` | `POST /fronts/{id}/members/{agent_key}/integration`; **sin fallback offline** (rc 5: `front_integration_reported` no existe en el catálogo v2, issue #44) |
 
+**Forma del borrador de `propose-epic --file`:**
+
+```json
+{
+  "title": "…",
+  "objective": "…",
+  "layer": "foundational|business|technical",
+  "files_scope": ["…"],
+  "depends_on": ["EP-012"],
+  "stories": [{"title": "…", "acceptance_criteria": "…"}]
+}
+```
+
+`title` y `objective` son obligatorios; `layer` por defecto `business` (rc 2 si no es una de las
+tres). Un `epic_code`/`code`/`id` en el borrador **se ignora con aviso**, no se rechaza la
+propuesta — la identidad la asigna el hub al aprobar (hub#113). El normalizador estampa
+`origin: "harness-draft"` antes de encolar.
+
 **Códigos de salida** (contrato con la prosa): `0` ok · `2` uso · `3` modo legacy (o claim en dual)
 · `4` sin slice activo · `5` offline (encolado si el tipo tiene camino por la cola; si no, reintento manual al reconectar) · `6` rechazado por el servidor (no reintentar) ·
 `7` sin trabajo.

package/hooks/build/design-source-guard.sh

@@ -18,7 +18,18 @@ HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$HERE/lib/projection.sh"
 if [ "$(runtime_mode)" = "runtime" ]; then
   CACHE="$(runtime_projection_path)"
-  [ -f "$CACHE" ] || exit 0
+  if [ ! -f "$CACHE" ]; then
+    # auto-arme (sin credenciales) vs desconectado (con credenciales): ver
+    # runtime_disconnected en lib/runtime-client.sh.
+    if runtime_disconnected; then
+      echo "⛔ sin conexión con el hub: hay credenciales del proyecto pero no hay proyección local." >&2
+      echo "   Este agente no sabe qué trabajo tiene asignado, así que no puede escribir código." >&2
+      echo "   Recupérala con \`slice-ops.sh status\` (refresca /agent/context) y reclama con \`/build:claim\`." >&2
+      echo "   Si esto es un worktree: el estado del arnés vive en el clon principal y no viaja al worktree." >&2
+      exit 2
+    fi
+    exit 0
+  fi
   if ! command -v python3 >/dev/null 2>&1; then
     echo "⛔ design-source-guard: python3 no disponible; no puedo verificar el gate de fuente de diseño. Instala python3 (trycore-build doctor)." >&2
     exit 2