@trycore/spec-build-harness 0.14.2 → 0.15.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.14.2",
+  "version": "0.15.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/README.md

@@ -80,6 +80,7 @@ Gate de release que corre **una sola vez por versión** sobre el conjunto de sli
 | `/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. |
+| `/build:graph-sync` | Propone el **re-sync del grafo** del hub desde los docs de discovery (modo `runtime`): el hub calcula el delta y un humano lo aprueba — nada se aplica sin esa aprobación. Con `--check` lee el veredicto. Sin esto, el grafo del hub se quedaba en la foto del import inicial y los eventos de las épicas posteriores rebotaban. |
 | `/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.14.2
+0.15.0

package/commands/build/graph-sync.md

@@ -0,0 +1,129 @@
+---
+name: "BUILD: Graph Sync"
+description: Propone al hub el re-sync del grafo del proyecto desde los docs de discovery (epicas.md + HU-*.md). El hub calcula el delta y un humano lo aprueba en la consola; nada se aplica sin esa aprobación. Con --check no propone nada: solo consulta el veredicto de las propuestas ya enviadas. Adaptador delgado sobre slice-ops.sh graph-sync/graph-sync-status.
+category: Workflow
+tags: [build-harness, runtime, backlog, grafo, trycore]
+---
+
+# /build:graph-sync — re-sincronizar el grafo del hub con los docs (la aprobación es humana)
+
+El grafo del hub se siembra una vez, con el **import de admin** de `/build:onboard`. A partir de
+ahí discovery sigue escribiendo: épicas nuevas en `docs/03-backlog/epicas.md`, historias nuevas
+en las `HU-*.md`. Sin este comando, nada de eso llega al hub — y el síntoma es concreto: **todos
+los eventos de un slice cuya épica no está en el grafo rebotan** con «la épica no existe en el
+grafo del proyecto».
+
+**Regla dura**: el arnés **propone**, un humano **aprueba**. Este comando no muta el grafo; deja
+una propuesta con su delta calculado, y hasta que alguien la apruebe en la consola del hub no
+cambia ni una arista.
+
+**Entrada (opcional):** `--check`. Sin argumento, el comando **propone** el re-sync.
+
+## Despacho por argumento (léelo antes que nada)
+
+- **Con `--check`** → ve directo al **§0** y luego **salta al §4**. `--check` es una consulta de
+  **solo lectura**: no construyas ningún bundle y no propongas nada (§1–§3 no se ejecutan, ni
+  siquiera "por si acaso"). Proponer aquí crearía una segunda propuesta del mismo grafo cada vez
+  que alguien comprueba el estado.
+- **Sin argumento** → §0 → §1 → §2 → §3. El §4 se recorre después, cuando el humano haya
+  resuelto la propuesta en la consola (normalmente en otra invocación, con `--check`).
+
+## 0. Precondición
+
+```bash
+bash .claude/hooks/build/slice-ops.sh mode
+```
+
+- `legacy` → **STOP**: el grafo vive en los documentos y no hay hub con el que sincronizarlo.
+- `dual` → **STOP** para proponer, pero aquí **sí hay hub**: el fichero local es el primario y el
+  grafo entra por el import de admin. No lo diagnostiques como un problema de conexión. El
+  `--dry-run` del §2 sí funciona: úsalo para revisar el grafo antes del corte a `runtime`.
+- `runtime` → sigue.
+
+## 1. Construir el JSON de épicas desde los docs
+
+Lee `docs/03-backlog/epicas.md` y las `HU-*.md` y escribe un fichero temporal con **todo** el
+backlog vigente, no solo lo nuevo: el hub compara el bundle contra su grafo y calcula el delta,
+así que mandar un subconjunto no borra nada pero tampoco describe el proyecto.
+
+```json
+{"project_ref": "<nombre del proyecto>",
+ "epics": [{"code": "EP-001", "title": "…", "layer": "foundational",
+            "files_scope": ["src/core/**"], "depends_on": [],
+            "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"]}]}
+```
+
+Es el **mismo formato** que la fase de grafo de `/build:onboard`: si ya lo generaste allí,
+reutilízalo. A diferencia de las propuestas de épica, aquí el `code` **sí** viaja: el re-sync es
+la puerta de lo que ya tiene identidad en los documentos.
+
+**No inventes ninguna épica ni ninguna capa.** Si un dato falta en los docs, falta en el grafo:
+se corrige en discovery, no aquí.
+
+## 2. Revisar antes de proponer (`--dry-run`)
+
+```bash
+bash .claude/hooks/build/slice-ops.sh graph-sync \
+  --file /tmp/epics.json --from-docs docs/03-backlog/epicas.md --dry-run
+```
+
+**Pasa siempre `--from-docs`**: 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; sin él, un backlog lleno de dependencias sale con `depends_on: []` y el Lienzo del
+hub queda sin una sola arista.
+
+`--dry-run` imprime el bundle ya proyectado al contrato del hub y **no envía nada**. Revísalo con
+el usuario: número de épicas, capas, aristas.
+
+Un `rc 2` aquí no es un fallo del comando: es el bundle incumpliendo el contrato del hub, con un
+motivo por línea que nombra la épica y el campo (`layer` ausente, historia sin `code`, techos
+excedidos). Corrígelo **en los docs de discovery** y repite. El hub rechaza el grafo entero ante
+una sola épica mal formada, así que estas comprobaciones se hacen aquí para no gastar un viaje.
+
+## 3. Proponer
+
+```bash
+bash .claude/hooks/build/slice-ops.sh graph-sync \
+  --file /tmp/epics.json --from-docs docs/03-backlog/epicas.md
+```
+
+| rc | Significado | Qué haces |
+|---|---|---|
+| `0` | Propuesta creada (el comando enseña el `id` y el delta), **o** el grafo ya estaba al día | Si hay `id`, dile al usuario que queda **pendiente de aprobación humana** en la consola. Si dice «ya está al día», no hay nada que hacer |
+| `5` | Encolada, aún sin entregar (sin conexión, o el daemon estaba drenando la cola) | Avisa de que se despachará sola y de que `--check` la sigue |
+| `6` | El hub la rechazó (422 con el motivo, 404, o falta `project_id`) | Muestra la razón; **no** reintentes en bucle |
+| `2` | El bundle no cumple el contrato, o falta `--file` | Corrige lo que indique el mensaje, en los docs |
+| `3` | `legacy`/`dual` | Vuelve al paso 0 |
+
+Un **409 de grafo rancio** no lo verás como error: el comando refresca el contexto y reintenta
+una vez con el mismo identificador, para que el hub deduplique en vez de crear una segunda
+propuesta del mismo grafo.
+
+## 4. Después de la decisión — `/build:graph-sync --check`
+
+**Aquí aterriza `--check`.** Es mecánico y de solo lectura:
+
+```bash
+bash .claude/hooks/build/slice-ops.sh graph-sync-status
+```
+
+- `APPROVED` (con la versión de grafo aplicada) → **no hay nada más que hacer**. Las historias
+  nuevas entran solas al reparto del claim: no hay que reclamar de otra forma ni tocar el estado.
+- `REJECTED` (con el motivo que escribió el ADMIN) → **léeselo al usuario**. El motivo existe
+  precisamente para que esta terminal lo lea. Corrige en discovery y vuelve a proponer.
+- `PROPOSED` → sigue esperando decisión humana. No propongas otra vez.
+- `QUEUED` → aún sin despachar; el daemon de heartbeat la lleva.
+
+## Guardrails
+
+- El arnés **propone**; la aprobación es humana (gobierno, METODOLOGIA §10 regla 8). Ni el
+  modelo ni el arnés aprueban un cambio de grafo.
+- **No edites `docs/03-backlog/epicas.md` para «arreglar» el bundle.** El fichero es la fuente;
+  si el bundle no cumple, lo que está mal es la fuente, y se corrige con el usuario delante.
+- **No propongas dos veces sin mirar `--check`.** Dos propuestas del mismo grafo esperando
+  aprobación es exactamente el ruido que este carril evita.
+- Un `REJECTED` **no** se resuelve reintentando: se resuelve leyendo el motivo.

package/dist/commands/init.js

@@ -230,6 +230,9 @@ function syncGitignoreBlock(targetDir, mode) {
         // sin esto, un consumidor los commitea por descuido.
         '.claude/state/epic-proposals.json',
         '.claude/state/graph-status.json',
+        // [EP-OR-17] El ledger del re-sync del grafo es lo mismo: el rastro local de una
+        // conversación con el hub, no estado del proyecto.
+        '.claude/state/graph-sync-proposals.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

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`, `/build:epic` — superficie de agente del runtime (beta, opt-in)
+### `/build:claim`, `/build:status`, `/build:escalate`, `/build:epic`, `/build:graph-sync` — 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.
@@ -140,6 +140,7 @@ protocolo del fichero (`/build:slice`) — no rompen el flujo normal si el proye
 | `/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. |
+| `/build:graph-sync` | Propone al hub el **re-sync del grafo** desde los docs de discovery (`epicas.md` + `HU-*.md`): el hub calcula el delta y un humano lo aprueba en la consola — **nada se aplica** sin esa aprobación. Existe porque el grafo del hub se sembraba una vez, con el import de admin, y todo lo que discovery escribía después no tenía por dónde entrar: el síntoma es que **cada evento de un slice cuya épica falta en el grafo rebota**. Con `--check` solo consulta el veredicto (`APPROVED` con la versión aplicada, o `REJECTED` con el motivo que escribió el ADMIN). Tras la aprobación no hay nada que hacer: las historias nuevas entran solas al reparto del claim. |
 
 ---
 

package/docs/runtime/guia-modo-dual-y-migracion.md

@@ -120,7 +120,7 @@ arman peticiones a mano. En `dual`, cada transición también se **espeja** al s
 identidad del fichero (que sigue mandando). Si el espejo falla (red caída, servidor rechaza), el
 trabajo local **nunca se bloquea** — se avisa y queda como discrepancia para el comparador.
 
-`slice-ops.sh` tiene **17 subcomandos** (los conducen las skills; los listamos para que puedas
+`slice-ops.sh` tiene **19 subcomandos** (los conducen las skills; los listamos para que puedas
 leer un log o depurar, no para que los teclees):
 
 | Subcomando | Para qué |
@@ -136,12 +136,47 @@ leer un log o depurar, no para que los teclees):
 | `fact` | reporta un hecho de proyecto confirmado |
 | `propose-asset` | propone un documento al plano de contexto (lo publica un ADMIN) |
 | `propose-epic` · `epic-status` · `epic-writeback` | proponen una épica, consultan su estado y proyectan la aprobada a `epicas.md` |
+| `graph-sync` · `graph-sync-status` | proponen el re-sync del grafo desde los docs de discovery y leen el veredicto humano (solo en `runtime`) |
 | `status` · `escalate` | informe local del agente y registro de un bloqueo |
 
 Del lado release, `release-ops.sh` añade `verdict` y `front-integration`.
 
 **Códigos de salida** (sobre estos ramifica la prosa de las skills): `0` ok · `2` uso · `3` legacy ·
-`4` sin slice · `5` offline · `6` rechazado · `7` sin trabajo.
+`4` sin slice · `5` offline · `6` rechazado · `7` sin trabajo · `8` tipo no espejable.
+
+### Qué espeja el modo `dual` — y qué no (0.15.0)
+
+El espejo cubre la **enumeración normativa** del hub, ni más ni menos: `slice_opened`,
+`phase_advanced`, `phase_reverted`, `gate_verdict`, `wiring_item_updated`,
+`wiring_checklist_seeded`, `checkpoint_recorded`, `progress_noted` y `handoff_recorded`. Todo eso
+viaja como `{"transitions": [{client_event_id, epic_code, event_type, payload}]}`, con la épica
+del `build-state.json` local en el **sobre**, y el hub responde un reporte **por elemento** cuyo
+motivo de rechazo el cliente te enseña tal cual.
+
+Lo que **no** se espeja, y por qué — son huecos del **hub**, no del arnés, y el cliente los corta
+en local (`rc 8`) en vez de gastar una llamada para recibir un rechazo:
+
+| No espejable | Motivo |
+|---|---|
+| `slice_escalated` · `slice_archived` · `slice_submitted` | Existen en el catálogo del hub pero no heredan de `_TransicionDeEspejo`: la ingesta espejo no los acepta. Una discrepancia dual sigue siendo **visible** donde la lees —el aviso del hook `Stop`—, pero no queda registrada en el hub. |
+| `release_verdict_reported` · `front_integration_reported` | No existen en el catálogo del hub, y la superficie síncrona de los veredictos de release es de **gobierno humano**. En `dual` el veredicto se anota en local y el comando te lo dice con esas palabras; quedará reflejado al pasar a `runtime`. |
+
+Cerrar estos huecos requiere un tipo nuevo en el catálogo del hub con su rama de reducer: es
+trabajo hub-side. Mientras tanto el arnés lo **nombra** en vez de fallar en silencio.
+
+### Cuando el hub no conoce tu épica (0.15.0)
+
+Si el espejo rechaza con «la épica no existe en el grafo del proyecto», el grafo del hub se quedó
+en la foto del import inicial. La salida es proponer el re-sync:
+
+```bash
+/build:graph-sync            # construye el bundle desde los docs y lo propone
+/build:graph-sync --check    # lee el veredicto: APPROVED, o REJECTED con su motivo
+```
+
+En `dual` el carril de propuesta no opera (el fichero es primario y el grafo entra por el import
+de admin), pero `slice-ops.sh graph-sync --file epics.json --dry-run` **sí** funciona: úsalo para
+revisar el grafo antes del corte a `runtime`.
 
 ### Lo que aportó la 0.14.0
 

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

@@ -177,11 +177,11 @@ agente jamás publica contexto.**
 | Situación | Comportamiento del cliente |
 |---|---|
 | `401/403` (token inválido/revocado) | Detener claims; mensaje accionable ("pide un token nuevo al ADMIN"); guards siguen operando con el último lock. |
-| `409` en claim | Un reintento inmediato; luego informar "otro agente tomó la tarea" y pedir la siguiente. |
+| `409` en claim | Un reintento inmediato; luego informar "otro agente tomó la tarea" y pedir la siguiente. Los motivos llegan **bajo `detail`**, no en la raíz: el **drift de contexto** se reconoce por FORMA (`detail` dict con `manifest_hash`, que es el hash al que sincronizar) y el resto por el texto que el hub construye en un solo sitio (contención → reintentable; «no hay trabajo sin contexto declarado» → `rc 6` sin reintento). Lo que el cliente enseña es la prosa del hub, nunca el JSON crudo. |
 | `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**). |
+| `409` de **grafo rancio** en `tasks/next` o en el carril directo | El hub lo emite como `{"detail": {"error": "graph_version_stale", "graph_version": <vigente>}}` — anidado bajo `detail`, que es donde FastAPI pone el cuerpo de un `HTTPException`. El cliente lo lee con `runtime_stale_graph_version`, que acepta esa forma y la plana `{"reason": "stale_graph"}` de una instancia anterior al contrato. Conducta: 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
@@ -271,13 +271,62 @@ El hub descarta los campos que no reconoce (`extra="ignore"`): mandar `acceptanc
 `7` sin trabajo.
 
 **Modo `dual`:** el fichero es primario y estos comandos **espejan** cada transición a
-`POST /projects/{project_id}/mirror/transitions` con la identidad fichero-primaria
-(`slice_ref: {epic_code, openspec_change, branch, phase}`) y `origin: "mirror"`. Un rechazo del
-reducer **no bloquea** el trabajo local: se avisa y queda como discrepancia del comparador.
+`POST /projects/{project_id}/mirror/transitions`. El cuerpo es `MirrorTransitionsIn`:
+
+```json
+{"transitions": [{"client_event_id": "<uuid>", "epic_code": "EP-009",
+                  "event_type": "gate_verdict", "payload": {…}}]}
+```
+
+La identidad fichero-primaria viaja como `epic_code` **en el sobre**, que es donde el hub la lee;
+dentro del `payload` no cabe nada que el schema del tipo no declare (`extra="forbid"`). Ni
+`origin` ni `occurred_at` viajan: la marca de origen-espejo la estampa el servidor —lo que dijera
+el cliente no elegiría el origen— y los relojes de cliente entran **solo** por el import. El
+reporte es **por elemento** (`results[].status` ∈ `applied|duplicate|rejected` con su `reason`), y
+un rechazo **no bloquea** el trabajo local: se avisa con el motivo del hub y queda como
+discrepancia del comparador.
+
+**Enumeración normativa del espejo** (`TIPOS_DE_ESPEJO`, replicada en `OPS_MIRROR_TYPES` con test
+anti-drift): `slice_opened`, `phase_advanced`, `phase_reverted`, `gate_verdict`,
+`wiring_item_updated`, `wiring_checklist_seeded`, `checkpoint_recorded`, `progress_noted`,
+`handoff_recorded`. Un tipo fuera de ella **no gasta red**: se corta en local con `rc 8`. Ahí caen
+`slice_escalated`, `slice_archived`, `slice_submitted` (existen en el catálogo del hub pero no son
+espejables) y `release_verdict_reported` / `front_integration_reported` (no existen en el catálogo:
+sus canales de espejo son trabajo **hub-side**).
+
+### Re-sync del grafo (`graph-sync` / `graph-sync-status`, EP-OR-17)
+
+El grafo del hub se siembra con el import de ADMIN y, hasta EP-OR-17, no volvía a moverse: las
+épicas que discovery añadía después no tenían por dónde entrar, y toda transición de un slice cuya
+épica falta en el grafo rebota con «la épica no existe en el grafo del proyecto». El carril nuevo
+lo cierra sin dar al agente la potestad de mutar el grafo — **propone**, el hub calcula el delta y
+un humano aprueba.
+
+| Verbo y ruta | Cuerpo | Respuestas |
+|---|---|---|
+| `POST /projects/{id}/agent/graph-sync-proposals` | `{"bundle": {"epics": […]}, "graph_version": <vigente\|null>, "client_event_id": "<≤64>"}` | `201` propuesta `PROPOSED` · `200 {"empty_delta": true}` el grafo ya está al día · `409` `detail` dict = grafo rancio, `detail` string = el `client_event_id` ya identifica otro agregado · `422` bundle inválido (rechazo total, sin fila ni evento) · `404` anti-oráculo |
+| `GET /projects/{id}/agent/graph-sync-proposals/{proposal_id}` | — | `200` con `status`, `delta`, `graph_version_applied` o `reject_reason` · `404` anti-oráculo |
+
+- El **bundle** lo construye `scripts/lib/graph-bundle.py --for-sync` desde los docs de discovery.
+  `GraphSyncBundle` es `extra="forbid"` y admite **solo** `epics`: las claves del bundle de
+  preparación (`bundle_version`, `kind`, `project_ref`, `warnings`…) serían un `422`. Lo que en el
+  bundle de import es un aviso aquí es un **rechazo local** (`rc 2`): no hay humano revisando en
+  medio, y el hub rechaza el grafo entero ante una sola épica mal formada.
+- El **`client_event_id` es determinista** (`<agent_key>:graph-sync:<n>`, con `n` = entradas del
+  ledger + 1; sha256 truncado del `agent_key` si no cabe en 64). El reintento lo reusa y el hub
+  deduplica, en vez de dejar dos propuestas del mismo grafo esperando aprobación.
+- El **reintento del 409** lo hace el comando, no el despachador: refresca `/agent/context` y
+  vuelve a despachar **una vez**, con lo que el estampado toma la versión nueva. El bundle no
+  depende de la versión del grafo, solo el sello que lo acompaña.
+- Tras la aprobación **no hay nada más que hacer**: las historias nuevas entran solas al reparto
+  del claim. La lógica de claim del cliente no cambia.
+- El **ledger local** vive en `.claude/state/graph-sync-proposals.json` (protegido en
+  `.gitignore`), separado del de propuestas de épica: un re-sync no es una propuesta de épica.
 
 **Lo que el agente NO hace** (superficies humanas, con PDP): cerrar una release, planificar/abrir/
-drenar/cerrar un front, subir el bundle de import del grafo y publicar contexto. El arnés prepara,
-propone y reporta; la persona decide en la consola del hub.
+drenar/cerrar un front, **aprobar o rechazar un re-sync del grafo**, subir el bundle de import del
+grafo y publicar contexto. El arnés prepara, propone y reporta; la persona decide en la consola del
+hub.
 
 ---
 

package/hooks/build/lib/runtime-client.sh

@@ -349,6 +349,41 @@ PY
 # runtime_graph_clear_stale — el desfase dejó de existir (la proyección alcanzó al servidor).
 runtime_graph_clear_stale() { rm -f "$(runtime_graph_status_path)" 2>/dev/null; return 0; }
 
+# runtime_stale_graph_version <respuesta-json> — ¿este 409 dice que nuestro grafo va rancio?
+# rc 0 = sí (imprime la versión vigente del servidor, o vacío si no la manda) · rc 1 = no.
+#
+# [EP-OR-17] Existe porque el cliente leía `{"reason":"stale_graph"}` en la RAÍZ y el hub emite
+# `{"detail":{"error":"graph_version_stale","graph_version":N}}` — un HTTPException de FastAPI
+# anida SIEMPRE bajo `detail`, y el literal `stale_graph` no aparece en ninguna parte de su
+# backend. Con la lectura vieja, un claim con grafo rancio NO se reintentaba y una propuesta se
+# apartaba como rechazo definitivo: dos caminos que existían para tolerar el desfase y que en
+# realidad nunca se tomaban. Se aceptan las dos formas — si una instancia anterior al contrato
+# emitiera la plana, seguiría entendiéndose.
+# Fail-CLOSED a propósito, al revés que el resto del cliente: ante JSON ilegible o sin python3
+# devuelve rc 1 («no es un stale»). Tratar un rechazo cualquiera como grafo rancio lo dejaría
+# reintentando en bucle contra un hub que nunca va a aceptarlo.
+runtime_stale_graph_version() {
+  command -v python3 >/dev/null 2>&1 || return 1
+  printf '%s' "$1" | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+except Exception:
+    raise SystemExit(1)
+if not isinstance(d,dict):
+    raise SystemExit(1)
+det=d.get("detail")
+fuente=det if isinstance(det,dict) else d
+marca=fuente.get("error") or fuente.get("reason") or ""
+if marca not in ("graph_version_stale","stale_graph"):
+    raise SystemExit(1)
+v=fuente.get("graph_version")
+if v is None:
+    v=d.get("graph_version")
+sys.stdout.write("" if v is None else str(v))
+' 2>/dev/null
+}
+
 RUNTIME_OUTBOX_MAX_BYTES=5242880
 RUNTIME_OUTBOX_MAX_AGE_S=259200
 # [EP-OR-08-C] Los hechos de dominio que emiten las skills (slice-ops.sh) tampoco se evictan:
@@ -408,7 +443,8 @@ PY
   runtime_outbox_enforce_cap >/dev/null
 }
 
-# runtime_enqueue_direct <type> <method> <path> <payload_file> [stamp_graph_version] — encola
+# runtime_enqueue_direct <type> <method> <path> <payload_file> [stamp_graph_version]
+#                        [client_event_id] — encola
 # una petición del CARRIL DIRECTO [#62]: un hecho que NO viaja en el lote de `POST /events`
 # sino a su propio endpoint (hoy: la propuesta de épica, hub#113). Comparte con la cola de
 # eventos el directorio, el formato en disco, la cota y el sentinela de flush; lo único
@@ -419,18 +455,25 @@ PY
 # [#63] Con `1` en el 5º argumento, el fichero se marca para que el DESPACHO le estampe la
 # versión de grafo vigente. Sellarla al encolar sería un error: una propuesta que espera dos
 # días en la cola offline saldría con la versión de hace dos días y nacería condenada al 409.
+# [EP-OR-17] El 6º argumento fija el `client_event_id` en vez de generarlo: lo usa el re-sync
+# del grafo, donde el reintento tiene que llevar la MISMA identidad para que el hub deduplique
+# en vez de crear una segunda propuesta. Vacío (o ausente) = uuid4, como siempre.
 runtime_enqueue_direct() {
-  local type="$1" method="$2" path="$3" pfile="$4" stamp="${5:-0}" dir
+  local type="$1" method="$2" path="$3" pfile="$4" stamp="${5:-0}" cid_fijo="${6:-}" dir
   dir="$(runtime_outbox_dir)"; mkdir -p "$dir"
   command -v python3 >/dev/null 2>&1 || return 1
-  python3 - "$dir" "$type" "$method" "$path" "$pfile" "$stamp" <<'PY' 2>/dev/null || return 1
+  python3 - "$dir" "$type" "$method" "$path" "$pfile" "$stamp" "$cid_fijo" <<'PY' 2>/dev/null || return 1
 import json,sys,os,tempfile,uuid,datetime
-dir_,typ,method,path,pfile,stamp=sys.argv[1],sys.argv[2],sys.argv[3],sys.argv[4],sys.argv[5],sys.argv[6]
+dir_,typ,method,path,pfile,stamp,cid_fijo=sys.argv[1],sys.argv[2],sys.argv[3],sys.argv[4],sys.argv[5],sys.argv[6],sys.argv[7]
 try:
     payload=json.load(open(pfile))
 except Exception:
     payload={}
-cid=str(uuid.uuid4())
+# [EP-OR-17] Un cid FIJADO por el productor es lo que hace idempotente el reintento: el hub
+# deduplica por `client_event_id`, así que re-encolar el mismo re-sync tras un 409 de grafo
+# rancio no crea una segunda propuesta del mismo grafo. Sin él se conserva el uuid4 de siempre,
+# que es lo que quiere el carril de propuesta de épica (cada propuesta es una épica distinta).
+cid=cid_fijo or str(uuid.uuid4())
 ts=datetime.datetime.now(datetime.timezone.utc)
 d={"client_event_id":cid,"type":typ,"channel":"direct","method":method,"path":path,
    "payload":payload,"enqueued_at":ts.strftime("%Y-%m-%dT%H:%M:%S.%fZ")}
@@ -779,7 +822,7 @@ PY
 # propuesta de épica) y compartir el backoff del lote dejaría los hechos de dominio del slice
 # esperando detrás de una propuesta. El ritmo real de reintento lo marca el ciclo del daemon.
 _runtime_dispatch_direct() {
-  local f rc=0 resp status type path method payload gv server_gv n409 prev_gv stamped reason
+  local f rc=0 resp status type path method payload gv server_gv n409 prev_gv stamped
   for f in "$@"; do
     [ -f "$f" ] || continue
     # [Ronda final] `gv` se reinicia POR ITERACIÓN: es `local` a la función y solo se asigna
@@ -821,17 +864,17 @@ _runtime_dispatch_direct() {
         # escaneo del nombre bajo `set -u` en esta bash — `${type}` lo aísla.
         _runtime_reject_file "$f" "el hub no expone $path (HTTP 404): esta instancia está sin soporte para «${type}» — actualiza el hub y vuelve a proponer" ;;
       409)
-        # [Ronda de arreglo 1, Important 4] El `reason` decide, igual que en `_claim_once`:
-        # un 409 por OTRA causa (propuesta duplicada, conflicto de estado…) no es un grafo
-        # rancio y tratarlo como tal apartaría la propuesta con un diagnóstico falso.
-        reason="$(printf '%s' "$resp" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("reason") or "")' 2>/dev/null)"
-        if [ "$reason" = "stale_graph" ]; then
+        # [Ronda de arreglo 1, Important 4] El cuerpo decide, igual que en `_claim_once`:
+        # un 409 por OTRA causa (client_event_id de otro agregado, conflicto de estado…) no es
+        # un grafo rancio y tratarlo como tal apartaría la propuesta con un diagnóstico falso.
+        # [EP-OR-17] La lectura vive en `runtime_stale_graph_version`, que conoce la forma real
+        # del hub (`detail.error`) además de la plana legacy que este sitio leía a mano.
+        if server_gv="$(runtime_stale_graph_version "$resp")"; then
           # No es un error de contrato: el grafo del hub cambió. Se anota el desfase (lo
           # muestra `status`) y la petición se CONSERVA — el refresco del heartbeat (#61)
           # traerá la versión nueva y el próximo ciclo la re-estampa. Con 3 rechazos seguidos
           # se deja de insistir: a esas alturas no es una carrera, y un bucle silencioso es
           # peor que un rechazo visible.
-          server_gv="$(printf '%s' "$resp" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("graph_version") or "")' 2>/dev/null)"
           runtime_graph_note_stale "$gv" "$server_gv"
           n409="$(_runtime_direct_field "$f" graph_409)"
           case "$n409" in ''|*[!0-9]*) n409=0 ;; esac