@trycore/spec-build-harness 0.14.1 → 0.15.0

package/hooks/build/slice-ops.sh

@@ -5,9 +5,10 @@
 #
 #   uso: slice-ops.sh <subcomando> [opciones]
 #   subcomandos IMPLEMENTADOS (13 del plan + phase, issue #52; + propose-epic/epic-status/
-#                epic-writeback, issue #62): mode | claim | next-step | phase | gate | submit |
-#                archive | wiring | progress | checkpoint | fact | propose-asset |
-#                propose-epic | epic-status | epic-writeback | status | escalate.
+#                epic-writeback, issue #62; + graph-sync/graph-sync-status, EP-OR-17):
+#                mode | claim | next-step | phase | gate | submit | archive | wiring |
+#                progress | checkpoint | fact | propose-asset | propose-epic | epic-status |
+#                epic-writeback | graph-sync | graph-sync-status | status | escalate.
 #
 # Contrato con la prosa: cada subcomando devuelve un código de salida tipado
 # (0 ok · 2 uso · 3 legacy · 4 sin slice · 5 offline · 6 rechazado · 7 sin trabajo) y
@@ -46,6 +47,11 @@ uso: slice-ops.sh <subcomando> [opciones]
   epic-writeback [--id P] [--file F]           escribe en epicas.md las épicas ya APROBADAS,
                                                 con el código que asignó el hub (F debe estar
                                                 bajo docs/03-backlog/: carve-out §9.2)
+  graph-sync --file epics.json [--dry-run]      propone al hub el re-sync del grafo desde los
+                                                docs de discovery (el humano aprueba; con
+                                                --dry-run solo enseña el bundle, sin enviar)
+  graph-sync-status [--id P]                    veredicto del re-sync (QUEUED|PROPOSED|
+                                                APPROVED|REJECTED con el motivo del ADMIN)
   status [--no-refresh]                         informe local del agente
   escalate «razón» | --file F [--gate G]        registra un bloqueo (la decisión es humana)
 
@@ -72,6 +78,78 @@ except Exception:
 ' "$2" 2>/dev/null
 }
 
+# [EP-OR-17] Los motivos del 409 del claim, como los emite el hub DE VERDAD.
+#
+# Este `case` esperaba `drift`/`contention`/`context_unresolvable`/`cross_project` como valor de
+# `reason` en la RAÍZ de la respuesta. Ninguno de esos literales existe en el backend del hub:
+# un HTTPException de FastAPI anida SIEMPRE bajo `detail`, y los cuatro casos llegan como
+#   • drift de contexto  → detail dict con `manifest_hash` (el hash al que sincronizar)
+#   • contención         → detail str «contención con otra escritura del contexto: reintenta…»
+#   • contexto irresoluble → detail str «…no hay trabajo sin contexto declarado»
+#   • lease ajeno/expirado → detail str «El lease está expirado, es de otro agente o no existe…»
+# Todos caían en el `*)` y salían como rechazo duro: un drift —que se resuelve sincronizando y
+# reintentando— dejaba al agente sin claim y sin saber por qué. La clasificación por FORMA (el
+# dict con manifest_hash) manda sobre la clasificación por texto, que solo se usa donde el hub
+# construye el mensaje en un único sitio. Se conserva la lectura plana por compatibilidad.
+
+# _claim_409_kind <json> — clasifica el 409: drift|contention|context_unresolvable|
+# cross_project|"" (desconocido).
+_claim_409_kind() {
+  command -v python3 >/dev/null 2>&1 || { echo ""; return; }
+  printf '%s' "$1" | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+except Exception:
+    print(""); raise SystemExit(0)
+if not isinstance(d,dict):
+    print(""); raise SystemExit(0)
+det=d.get("detail")
+# Compatibilidad: una instancia que sí nombrara el motivo en un campo manda sobre el texto.
+for fuente in (det if isinstance(det,dict) else {}, d):
+    marca=fuente.get("reason") or fuente.get("error")
+    if isinstance(marca,str) and marca:
+        print(marca); raise SystemExit(0)
+# El drift se reconoce por FORMA, no por texto: el borde del hub garantiza el `manifest_hash`
+# en el cuerpo precisamente para que el cliente sepa a qué contexto sincronizar.
+if isinstance(det,dict) and det.get("manifest_hash"):
+    print("drift"); raise SystemExit(0)
+texto=det if isinstance(det,str) else (det.get("message","") if isinstance(det,dict) else "")
+t=str(texto).lower()
+if "contenci" in t:
+    print("contention")
+elif "no hay trabajo sin contexto" in t:
+    print("context_unresolvable")
+elif "otro agente" in t or "otro proyecto" in t:
+    print("cross_project")
+else:
+    print("")
+' 2>/dev/null
+}
+
+# _claim_409_text <json> — el motivo del hub en prosa, para enseñárselo al humano sin volcarle
+# el JSON crudo encima. Cae al cuerpo entero si no hay nada mejor.
+_claim_409_text() {
+  command -v python3 >/dev/null 2>&1 || { printf '%s' "$1"; return; }
+  printf '%s' "$1" | python3 -c '
+import json,sys
+crudo=sys.stdin.read()
+try:
+    d=json.loads(crudo)
+except Exception:
+    print(crudo.strip()); raise SystemExit(0)
+if not isinstance(d,dict):
+    print(crudo.strip()); raise SystemExit(0)
+det=d.get("detail")
+if isinstance(det,str) and det:
+    print(det)
+elif isinstance(det,dict):
+    print(det.get("message") or json.dumps(det,ensure_ascii=False))
+else:
+    print(crudo.strip())
+' 2>/dev/null
+}
+
 # _claim_render <json> — resumen compacto del slice reclamado (lo lee el humano y el modelo).
 _claim_render() {
   command -v python3 >/dev/null 2>&1 || { echo "$1"; return; }
@@ -127,31 +205,33 @@ _claim_once() {
       echo "NO_WORK: el runtime no tiene trabajo disponible para este agente"
       return $OPS_RC_NO_WORK ;;
     409)
-      reason="$(_claim_field "$resp" reason)"
-      [ -n "$reason" ] || reason="$(_claim_field "$resp" error)"
+      # [EP-OR-17] El grafo rancio se comprueba ANTES del `case`, con el helper del cliente:
+      # conoce la forma REAL del hub (`detail.error = graph_version_stale`) además de la plana
+      # que este sitio leía a mano y que el hub no emite en ninguna parte.
+      local server_gv
+      if server_gv="$(runtime_stale_graph_version "$resp")"; then
+        # [#63] No es un error: es la señal de que operamos contra una foto vieja del
+        # backlog. Se anota el desfase (lo muestra `status`) y se pide UN reintento con la
+        # proyección refrescada. Mismo patrón que el 409 del lease en hb_renew.
+        runtime_graph_note_stale "$gv" "$server_gv"
+        echo "⚠ 409 (graph_version_stale): el grafo local (v${gv:-?}) va por detrás del hub (v${server_gv:-?})" >&2
+        return 21
+      fi
+      reason="$(_claim_409_kind "$resp")"
       case "$reason" in
-        stale_graph)
-          # [#63] No es un error: es la señal de que operamos contra una foto vieja del
-          # backlog. Se anota el desfase (lo muestra `status`) y se pide UN reintento con la
-          # proyección refrescada. Mismo patrón que el 409 del lease en hb_renew.
-          local server_gv
-          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"
-          echo "⚠ 409 (stale_graph): el grafo local (v${gv:-?}) va por detrás del hub (v${server_gv:-?})" >&2
-          return 21 ;;
         drift|contention)
-          echo "⚠ 409 ($reason): reintentable" >&2
+          echo "⚠ 409 ($reason): reintentable — $(_claim_409_text "$resp")" >&2
           return 20 ;;
         context_unresolvable)
-          echo "⛔ 409 contexto irresoluble — NO reintentar: $resp" >&2
+          echo "⛔ 409 contexto irresoluble — NO reintentar: $(_claim_409_text "$resp")" >&2
           echo "  Resuélvelo en el hub (propuesta → publicación) y vuelve a reclamar." >&2
           return $OPS_RC_REJECTED ;;
         cross_project)
-          echo "⛔ 409 cruce de proyecto (queda auditado en el servidor): $resp" >&2
+          echo "⛔ 409 cruce de proyecto (queda auditado en el servidor): $(_claim_409_text "$resp")" >&2
           echo "  Este clon está registrado contra otro proyecto: revisa runtime.credentials." >&2
           return $OPS_RC_REJECTED ;;
         *)
-          echo "⛔ 409 sin razón reconocida en el cuerpo: $resp" >&2
+          echo "⛔ 409 del hub: $(_claim_409_text "$resp")" >&2
           return $OPS_RC_REJECTED ;;
       esac ;;
     401|403)
@@ -322,11 +402,15 @@ cmd_fact() {
 # escribible, python3 ausente u otro fallo local) — el caller decide qué avisar y nunca debe
 # reportar éxito en ese caso (fail-open sobre el trabajo local, nunca sobre el reporte).
 _ops_emit_event() {
-  local tipo="$1" payload="$2" sid="${3:-}" pfile mode
+  local tipo="$1" payload="$2" sid="${3:-}" pfile mode epic
   mode="$(ops_mode)"
   pfile="$(ops_tmpjson "$payload")" || return $OPS_RC_OFFLINE
   if [ "$mode" = "dual" ]; then
-    ops_mirror "$tipo" "$pfile" || echo "⚠ «${tipo}» no espejado; el comparador dual lo marcará" >&2
+    # [EP-OR-17] El `epic_code` va en el SOBRE del espejo, que es donde el hub lo lee. Muchos de
+    # los tipos que pasan por aquí (hechos de proyecto, archivado, escalada) no son espejables:
+    # `ops_mirror` los corta en local con rc 8 antes de gastar una llamada.
+    epic="$(ops_local_slice_ref | python3 -c 'import json,sys; print(json.load(sys.stdin).get("epic_code") or "")' 2>/dev/null)"
+    ops_mirror "$tipo" "$pfile" "$epic" || echo "⚠ «${tipo}» no espejado; el comparador dual lo marcará" >&2
     rm -f "$pfile"
     return $OPS_RC_OK
   fi
@@ -485,8 +569,29 @@ _epic_draft_normalize() {
   # el motivo del rc 2 (validación) o el aviso de `epic_code` ignorado; silenciarlo aquí
   # los perdería a los dos.
   python3 - "$f" <<'PY'
-import json,sys
-CAPAS={"foundational","business","technical"}
+import json,re,sys
+# [#70] El vocabulario del BORRADOR (lo que escribe el agente) y el del CONTRATO del hub
+# (`EpicProposalIn`) no son el mismo: el borrador habla en minúsculas y conoce `technical`;
+# el hub solo acepta el literal FOUNDATIONAL|BUSINESS. La traducción vive aquí, en el borde,
+# porque rechazar `technical` sería castigar al agente por una distinción que el grafo no
+# hace: para el hub una épica técnica es de negocio.
+CAPAS={"foundational":"FOUNDATIONAL","business":"BUSINESS","technical":"BUSINESS"}
+
+def escenarios(txt):
+    """Criterios en prosa -> `acceptance[]` del contrato: un escenario Dado/Cuando/Entonces
+    por entrada. Se parte por líneas y, dentro de cada una, por el `. Dado ` que separa dos
+    escenarios seguidos en un mismo párrafo."""
+    out=[]
+    for linea in str(txt).splitlines():
+        linea=linea.strip().lstrip("-*•").strip()
+        if not linea:
+            continue
+        for trozo in re.split(r"\.\s+(?=Dado\s)", linea):
+            trozo=trozo.strip()
+            if trozo:
+                out.append(trozo[:2000])
+    return out[:20]
+
 try:
     d=json.load(open(sys.argv[1]))
 except Exception:
@@ -499,29 +604,77 @@ if not title:
     print("⛔ el borrador no trae `title` (título de la épica)", file=sys.stderr); raise SystemExit(2)
 if not objective:
     print("⛔ el borrador no trae `objective` (objetivo de la épica)", file=sys.stderr); raise SystemExit(2)
-layer=d.get("layer") or "business"
+layer=str(d.get("layer") or "business").strip().lower()
 if layer not in CAPAS:
     print("⛔ `layer` debe ser uno de: %s" % ", ".join(sorted(CAPAS)), file=sys.stderr); raise SystemExit(2)
 ignorados=[k for k in ("epic_code","code","id") if d.get(k)]
 stories=[]
 for s in d.get("stories") or []:
     if isinstance(s,str):
-        stories.append({"title":s})
+        stories.append({"title":s[:300]})
     elif isinstance(s,dict) and (s.get("title") or "").strip():
-        st={"title":s["title"].strip()}
-        if s.get("acceptance_criteria"):
-            st["acceptance_criteria"]=str(s["acceptance_criteria"])[:2000]
+        st={"title":s["title"].strip()[:300]}
+        if s.get("description"):
+            st["description"]=str(s["description"])[:2000]
+        # La `acceptance` explícita del borrador manda; si no, se derivan de los criterios en
+        # prosa. `acceptance_criteria` NO viaja: el hub descarta el campo en el borde
+        # (`extra="ignore"`) y la consola enseñaba las historias sin un solo criterio.
+        acc=s.get("acceptance")
+        if isinstance(acc,list):
+            acc=[str(x).strip()[:2000] for x in acc if str(x).strip()][:20]
+        elif s.get("acceptance_criteria"):
+            acc=escenarios(s["acceptance_criteria"])
+        else:
+            acc=[]
+        if acc:
+            st["acceptance"]=acc
         stories.append(st)
-out={"title":title[:300],"objective":objective[:2000],"layer":layer,
+out={"title":title[:300],"objective":objective[:2000],"layer":CAPAS[layer],
      "files_scope":[str(x) for x in (d.get("files_scope") or []) if isinstance(x,(str,int))],
      "depends_on":[str(x) for x in (d.get("depends_on") or []) if isinstance(x,(str,int))],
-     "stories":stories,"origin":"harness-draft"}
+     "stories":stories}
 if ignorados:
     print("IGNORADOS %s" % ",".join(ignorados), file=sys.stderr)
 print(json.dumps(out,ensure_ascii=False))
 PY
 }
 
+# [#70] `EpicProposalOut` del contrato nombra `id` al identificador de la propuesta (el
+# borrador de hub#113 lo llamaba `proposal_id`). Sin esto la terminal decía «sin identificador
+# en la respuesta» y el ledger guardaba "" — `epic-status` se quedaba sin a quién preguntar.
+# Se acepta el nombre viejo como respaldo: un hub anterior al contrato sigue funcionando.
+_epic_proposal_id() {
+  command -v python3 >/dev/null 2>&1 || { echo ""; return; }
+  printf '%s' "$1" | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+    r=(d.get("response") if isinstance(d.get("response"),dict) else d) or {}
+    print(r.get("id") or r.get("proposal_id") or "")
+except Exception:
+    print("")
+' 2>/dev/null
+}
+
+# _epic_from_response <respuesta> — la épica aprobada como objeto para el ledger. El contrato
+# la devuelve en la RAÍZ de `EpicProposalOut`; el borrador viejo la anidaba en `epic`.
+_epic_from_response() {
+  command -v python3 >/dev/null 2>&1 || { echo "{}"; return; }
+  printf '%s' "$1" | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+except Exception:
+    print("{}"); raise SystemExit(0)
+if not isinstance(d,dict):
+    print("{}"); raise SystemExit(0)
+e=d.get("epic")
+if not isinstance(e,dict):
+    e={k:d[k] for k in ("title","objective","layer","stories","files_scope","depends_on") if k in d}
+print(json.dumps(e,ensure_ascii=False))
+' 2>/dev/null || echo "{}"
+}
+
 cmd_propose_epic() {
   local file="" mode pid norm errf rc cid pfile ack proposal_id reason
   while [ $# -gt 0 ]; do
@@ -590,7 +743,7 @@ cmd_propose_epic() {
   runtime_dispatch_outbox >/dev/null 2>&1
   ack="$(ops_epic_ack_read "$cid")"
   if [ -n "$ack" ]; then
-    proposal_id="$(printf '%s' "$ack" | python3 -c 'import json,sys; print((json.load(sys.stdin).get("response") or {}).get("proposal_id") or "")' 2>/dev/null)"
+    proposal_id="$(_epic_proposal_id "$ack")"
     ops_epic_ledger_upsert "{\"client_event_id\":\"$cid\",\"status\":\"PROPOSED\",\"proposal_id\":$(ops_json_str "$proposal_id")}"
     echo "propuesta enviada: ${proposal_id:-sin identificador en la respuesta}"
     echo "Queda en PROPOSED: NO es reclamable hasta que un humano la apruebe en la consola del hub."
@@ -662,7 +815,7 @@ cmd_epic_status() {
     if [ "$st" = "QUEUED" ] && [ -n "$cid" ]; then
       ack="$(ops_epic_ack_read "$cid")"
       if [ -n "$ack" ]; then
-        pidv="$(printf '%s' "$ack" | python3 -c 'import json,sys; print((json.load(sys.stdin).get("response") or {}).get("proposal_id") or "")' 2>/dev/null)"
+        pidv="$(_epic_proposal_id "$ack")"
         st=PROPOSED
         ops_epic_ledger_upsert "{\"client_event_id\":\"$cid\",\"status\":\"PROPOSED\",\"proposal_id\":$(ops_json_str "$pidv")}"
       else
@@ -686,13 +839,18 @@ cmd_epic_status() {
           case "$st" in
             APPROVED)
               local code epic
-              code="$(_claim_field "$resp" epic_code)"
-              epic="$(printf '%s' "$resp" | python3 -c 'import json,sys; print(json.dumps(json.load(sys.stdin).get("epic") or {},ensure_ascii=False))' 2>/dev/null)"
+              # [#70] El código lo asigna el hub en `assigned_code` (EP-OR-15); `epic_code` era
+              # el nombre del borrador y se conserva como respaldo.
+              code="$(_claim_field "$resp" assigned_code)"
+              [ -n "$code" ] || code="$(_claim_field "$resp" epic_code)"
+              epic="$(_epic_from_response "$resp")"
               [ -n "$epic" ] || epic="{}"
               ops_epic_ledger_upsert "{\"client_event_id\":\"$cid\",\"status\":\"APPROVED\",\"epic_code\":$(ops_json_str "$code"),\"epic\":$epic}"
               echo "$pidv  APPROVED     $code — escríbela con \`slice-ops.sh epic-writeback\`" ;;
             REJECTED)
-              local why; why="$(_claim_field "$resp" reason)"
+              # [#70] El motivo del rechazo humano viaja en `reject_reason` (EP-OR-15).
+              local why; why="$(_claim_field "$resp" reject_reason)"
+              [ -n "$why" ] || why="$(_claim_field "$resp" reason)"
               ops_epic_ledger_upsert "{\"client_event_id\":\"$cid\",\"status\":\"REJECTED\",\"reason\":$(ops_json_str "$why")}"
               echo "$pidv  REJECTED     ${why:-sin motivo registrado}" ;;
             *)
@@ -871,6 +1029,294 @@ PY
   return $OPS_RC_OK
 }
 
+# ── graph-sync ───────────────────────────────────────────────────────────────────────
+# [EP-OR-17] Hasta ahora el grafo del hub dejaba de evolucionar tras el import inicial de
+# ADMIN: las épicas que discovery añadía después no tenían por dónde entrar, y TODOS los
+# eventos de un slice cuya épica no está en el grafo rebotan con «la épica no existe en el
+# grafo del proyecto». Este carril lo cierra sin regalarle al agente la potestad de mutar el
+# grafo: el arnés PROPONE el bundle, el hub calcula el delta y un humano aprueba en la consola.
+
+# _graph_sync_bundle <fichero-epics> [from_docs] — imprime el bundle proyectado al contrato,
+# o "" con rc 2 (no cumple el contrato) / rc 5 (falta infraestructura local).
+_graph_sync_bundle() {
+  local f="$1" docs="${2:-}" gb
+  gb="$HERE/../../scripts/lib/graph-bundle.py"
+  [ -f "$gb" ] || gb="$(config_root)/.claude/scripts/lib/graph-bundle.py"
+  if [ ! -f "$gb" ]; then
+    echo "⛔ no se encuentra graph-bundle.py: reinstala con \`trycore-build update\`" >&2
+    return $OPS_RC_OFFLINE
+  fi
+  # [Importante] Sin python3 no es "bundle inválido" (rc 2 de uso): es una degradación de
+  # infraestructura. Se anuncia con esas palabras para que no se confunda con un backlog mal
+  # escrito, que es lo que el agente iría a arreglar.
+  command -v python3 >/dev/null 2>&1 || {
+    echo "⛔ sin python3: no se puede construir el bundle en local" >&2
+    return $OPS_RC_OFFLINE
+  }
+  if [ -n "$docs" ]; then
+    python3 "$gb" --for-sync --from-docs "$docs" < "$f"
+  else
+    python3 "$gb" --for-sync < "$f"
+  fi
+}
+
+# _graph_sync_out <respuesta> <clave> — escalar de la respuesta del hub ("" si falta). Acepta
+# tanto el cuerpo desnudo como el sobre `{"response": …}` con el que el carril directo guarda
+# los acks, que es de donde lo lee este comando.
+_graph_sync_out() {
+  command -v python3 >/dev/null 2>&1 || { echo ""; return; }
+  printf '%s' "$1" | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+    r=(d.get("response") if isinstance(d.get("response"),dict) else d) or {}
+    v=r.get(sys.argv[1])
+    print("" if v is None else (v if isinstance(v,str) else json.dumps(v,ensure_ascii=False)))
+except Exception:
+    print("")
+' "$2" 2>/dev/null
+}
+
+# _graph_sync_delta_render <delta-json> — resumen legible del delta que devuelve el hub. Es lo
+# que el humano va a aprobar: enseñarlo aquí evita que el agente proponga a ciegas.
+_graph_sync_delta_render() {
+  command -v python3 >/dev/null 2>&1 || return 0
+  printf '%s' "$1" | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+except Exception:
+    raise SystemExit(0)
+if not isinstance(d,dict):
+    raise SystemExit(0)
+print("delta propuesto: %d épicas nuevas · %d épicas con cambios · %d historias nuevas · %d historias con cambios"
+      % (len(d.get("epics_added") or []), len(d.get("epics_changed") or []),
+         len(d.get("stories_added") or []), len(d.get("stories_changed") or [])))
+for e in (d.get("epics_added") or [])[:10]:
+    print("  + %s %s" % (e.get("code",""), e.get("title","")))
+for e in (d.get("epics_changed") or [])[:10]:
+    print("  ~ %s (%s)" % (e.get("code",""), ", ".join(sorted((e.get("fields") or {}).keys()))))
+' 2>/dev/null
+}
+
+cmd_graph_sync() {
+  local file="" docs="" dry=0 mode pid bundle rc cid pfile n_epicas
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --file) file="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --from-docs) docs="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --dry-run) dry=1; shift ;;
+      *) shift ;;
+    esac
+  done
+  if [ -z "$file" ]; then
+    echo "uso: slice-ops.sh graph-sync --file epics.json [--from-docs docs/03-backlog/epicas.md] [--dry-run]" >&2
+    echo "  epics.json: {\"epics\":[{code,title,layer,files_scope[],depends_on[],stories[]}]}" >&2
+    echo "  lo escribes leyendo docs/03-backlog/epicas.md y las HU-*.md (igual que en /build:onboard)." >&2
+    return $OPS_RC_USAGE
+  fi
+  [ -f "$file" ] || { echo "⛔ no existe el fichero de épicas: $file" >&2; return $OPS_RC_USAGE; }
+  [ -z "$docs" ] || [ -f "$docs" ] || { echo "⛔ no existe el documento de épicas: $docs" >&2; return $OPS_RC_USAGE; }
+
+  # El bundle se construye ANTES de mirar el modo: `--dry-run` tiene que servir también en
+  # legacy y dual, que es donde más falta hace revisar el grafo antes de registrarse.
+  bundle="$(_graph_sync_bundle "$file" "$docs")"
+  rc=$?
+  if [ $rc -ne 0 ] || [ -z "$bundle" ]; then
+    [ $rc -eq $OPS_RC_OFFLINE ] && return $OPS_RC_OFFLINE
+    echo "⛔ el bundle no se envía: corrige los docs de discovery y vuelve a intentarlo." >&2
+    return $OPS_RC_USAGE
+  fi
+  if [ "$dry" = 1 ]; then
+    printf '%s\n' "$bundle"
+    echo "--dry-run: nada se ha enviado. Quita la opción para proponer el re-sync al hub." >&2
+    return $OPS_RC_OK
+  fi
+
+  mode="$(ops_mode)"
+  if [ "$mode" != "runtime" ]; then
+    echo "${mode}: el re-sync del grafo solo opera en modo \`runtime\`."
+    echo "Con el fichero local como fuente de verdad, el grafo vive en los documentos y entra"
+    echo "al hub por el import de admin (\`/build:onboard\`). Usa --dry-run para revisarlo."
+    return $OPS_RC_LEGACY
+  fi
+  pid="$(runtime_field project_id)"
+  [ -n "$pid" ] || { echo "⛔ sin project_id en runtime.credentials: corre \`trycore-build init\`" >&2; return $OPS_RC_REJECTED; }
+
+  cid="$(ops_graph_sync_cid)"
+  # El cid es determinista, luego REUTILIZABLE: si el ledger se pierde o se limpia, el
+  # contador vuelve atrás y el rastro local de un envío anterior con ese mismo cid (su ack o
+  # su apartado) seguiría en disco. Leerlo haría que este comando reportara el resultado de
+  # una propuesta que NO acaba de enviar. Se retira antes de encolar: el hub sigue
+  # deduplicando por cid igualmente, así que borrar el rastro local no duplica nada.
+  rm -f "$(runtime_outbox_dir)/acks/${cid}.json" 2>/dev/null
+  rm -f "$(runtime_outbox_dir)/rejected/"*"${cid}.json" 2>/dev/null
+  pfile="$(ops_tmpjson "{\"bundle\":$bundle}")" || return $OPS_RC_OFFLINE
+  # El `1` pide el estampado de `graph_version` AL DESPACHAR: un re-sync que espera en la cola
+  # offline debe salir con la versión vigente en ese momento, no con la de ayer. El `$cid` fija
+  # la identidad: el reintento tras un 409 la reusa y el hub deduplica.
+  cid="$(runtime_enqueue_direct graph_sync_proposed POST "$(ops_path_graph_sync_proposals "$pid")" "$pfile" 1 "$cid")"
+  rm -f "$pfile"
+  if [ -z "$cid" ]; then
+    echo "⛔ no se pudo encolar el re-sync (outbox no escribible): reintenta." >&2
+    return $OPS_RC_OFFLINE
+  fi
+  n_epicas="$(printf '%s' "$bundle" | python3 -c 'import json,sys; print(len(json.load(sys.stdin)["epics"]))' 2>/dev/null || echo 0)"
+  ops_graph_sync_ledger_upsert "{\"client_event_id\":$(ops_json_str "$cid"),\"status\":\"QUEUED\",\"proposal_id\":null,\"epics\":$n_epicas}"
+
+  _graph_sync_despachar "$cid"
+}
+
+# _graph_sync_despachar <cid> — despacha, interpreta el resultado y, ante un grafo rancio,
+# refresca la proyección y reintenta UNA vez.
+#
+# El reintento vive AQUÍ y no en el despachador porque `runtime-client.sh` es agnóstico al
+# dominio: no sabe qué es un bundle ni cuándo vale la pena volver a intentarlo. Y re-estampar
+# con la versión nueva ES «recalcular el bundle contra la versión que devuelve el hub»: el
+# bundle no depende de la versión del grafo, solo el sello que lo acompaña.
+_graph_sync_despachar() {
+  local cid="$1" intento=1 ack reason id_prop delta
+  while :; do
+    runtime_dispatch_outbox >/dev/null 2>&1
+    ack="$(ops_epic_ack_read "$cid")"
+    if [ -n "$ack" ]; then
+      if [ "$(_graph_sync_out "$ack" empty_delta)" = "true" ]; then
+        # HU-OR-72 E2: no es un error ni una propuesta — el bundle coincide con el grafo
+        # vigente. Se cierra la entrada del ledger para que `graph-sync-status` no vaya a
+        # preguntar por una propuesta que el hub nunca creó.
+        ops_graph_sync_ledger_upsert "{\"client_event_id\":$(ops_json_str "$cid"),\"status\":\"EMPTY_DELTA\"}"
+        echo "el grafo del hub ya está al día: no hay cambios que proponer."
+        return $OPS_RC_OK
+      fi
+      id_prop="$(_graph_sync_out "$ack" id)"
+      delta="$(_graph_sync_out "$ack" delta)"
+      ops_graph_sync_ledger_upsert "{\"client_event_id\":$(ops_json_str "$cid"),\"status\":\"PROPOSED\",\"proposal_id\":$(ops_json_str "$id_prop")}"
+      echo "re-sync propuesto: ${id_prop:-sin identificador en la respuesta}"
+      [ -n "$delta" ] && _graph_sync_delta_render "$delta"
+      echo "Queda en PROPOSED: NADA se ha aplicado al grafo hasta que un humano lo apruebe en"
+      echo "la consola del hub. Sigue el veredicto con \`slice-ops.sh graph-sync-status\`."
+      return $OPS_RC_OK
+    fi
+    reason="$(ops_epic_rejected_reason "$cid")"
+    if [ -n "$reason" ]; then
+      ops_graph_sync_ledger_upsert "{\"client_event_id\":$(ops_json_str "$cid"),\"status\":\"FAILED\",\"reason\":$(ops_json_str "$reason")}"
+      case "$reason" in
+        *"HTTP 404"*|*404*)
+          # Anti-oráculo (HU-OR-72 E4): el hub responde lo MISMO para «no existe» y «no es
+          # tuyo». Afirmar una de las dos causas mandaría a buscar el problema equivocado.
+          echo "⛔ el hub respondió 404. Son dos causas indistinguibles POR DISEÑO: o el proyecto" >&2
+          echo "  no existe, o no es el tuyo (el hub no confirma cuál para no filtrar proyectos" >&2
+          echo "  ajenos). Verifica el project_id de runtime.credentials y que el hub tenga" >&2
+          echo "  la superficie de re-sync (EP-OR-17)." >&2 ;;
+        *) echo "⛔ el hub rechazó el re-sync: $reason" >&2 ;;
+      esac
+      return $OPS_RC_REJECTED
+    fi
+    # Sigue en la cola. Si fue por grafo rancio, el despachador dejó el marcador de desfase: se
+    # refresca la proyección y se reintenta UNA vez con la versión nueva.
+    if [ "$intento" = 1 ] && [ -n "$(runtime_graph_status_read)" ] && [ "$(runtime_graph_status_read)" != "{}" ]; then
+      intento=2
+      echo "⚠ el hub dice que nuestro grafo va rancio: se refresca el contexto y se reintenta una vez." >&2
+      agent_context_fetch_and_cache >/dev/null 2>&1 || \
+        echo "⚠ no se pudo refrescar /agent/context: el reintento sale con la versión que haya" >&2
+      # El despacho lleva mutex y estado de backoff: sin limpiarlo, el segundo intento cedería
+      # el turno y el reintento no ocurriría en este proceso.
+      rm -f "$(runtime_outbox_dir)/.dispatch-state.json" 2>/dev/null
+      continue
+    fi
+    echo "re-sync encolado: $cid"
+    echo "PENDIENTE: se despachará solo (el daemon de heartbeat lo lleva). Sin conexión aún, o el"
+    echo "daemon estaba drenando la cola en este instante. \`slice-ops.sh graph-sync-status\` lo sigue."
+    return $OPS_RC_OFFLINE
+  done
+}
+
+# ── graph-sync-status ────────────────────────────────────────────────────────────────
+# [EP-OR-17] El motivo del rechazo lo escribe el ADMIN precisamente para que lo lea la terminal
+# que propuso: sin este subcomando el veredicto humano se queda en la consola del hub y el
+# agente vuelve a proponer exactamente lo mismo. Informativo: rc 0 siempre en runtime, pase lo
+# que pase — es una consulta, y fallar aquí no arregla nada.
+cmd_graph_sync_status() {
+  local only="" mode pid entries n i cid pidv st resp status reason ack
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --id) only="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  mode="$(ops_mode)"
+  if [ "$mode" != "runtime" ]; then
+    echo "${mode}: no hay hub al que preguntar por el re-sync del grafo."
+    return $OPS_RC_LEGACY
+  fi
+  pid="$(runtime_field project_id)"
+  entries="$(ops_graph_sync_ledger_read)"
+  n="$(printf '%s' "$entries" | python3 -c 'import json,sys; print(len(json.load(sys.stdin).get("proposals") or []))' 2>/dev/null || echo 0)"
+  case "$n" in ''|*[!0-9]*) n=0 ;; esac
+  if [ "$n" = 0 ]; then
+    echo "no hay ninguna propuesta de re-sync registrada en esta terminal."
+    echo "Propón una con \`slice-ops.sh graph-sync --file epics.json\`."
+    return $OPS_RC_OK
+  fi
+  i=0
+  while [ "$i" -lt "$n" ]; do
+    cid="$(printf '%s' "$entries" | python3 -c 'import json,sys; print(json.load(sys.stdin)["proposals"][int(sys.argv[1])].get("client_event_id") or "")' "$i" 2>/dev/null)"
+    pidv="$(printf '%s' "$entries" | python3 -c 'import json,sys; print(json.load(sys.stdin)["proposals"][int(sys.argv[1])].get("proposal_id") or "")' "$i" 2>/dev/null)"
+    st="$(printf '%s' "$entries" | python3 -c 'import json,sys; print(json.load(sys.stdin)["proposals"][int(sys.argv[1])].get("status") or "")' "$i" 2>/dev/null)"
+    i=$((i + 1))
+    [ -z "$only" ] || [ "$only" = "$pidv" ] || [ "$only" = "$cid" ] || continue
+    if [ -z "$pidv" ]; then
+      # Todavía sin identificador del hub: el estado lo dicta el carril directo local, no la red.
+      ack="$(ops_epic_ack_read "$cid")"
+      reason="$(ops_epic_rejected_reason "$cid")"
+      if [ "$st" = "EMPTY_DELTA" ]; then
+        echo "$cid  EMPTY_DELTA  (el grafo ya estaba al día: el hub no creó ninguna propuesta)"
+      elif [ -n "$reason" ]; then
+        echo "$cid  FAILED  $reason"
+      elif [ -n "$ack" ]; then
+        echo "$cid  PROPOSED (ack recibido, sin identificador legible en la respuesta)"
+      else
+        echo "$cid  ${st:-QUEUED}  (pendiente de despacho: el daemon de heartbeat la lleva)"
+      fi
+      continue
+    fi
+    resp="$(runtime_get "$(ops_path_graph_sync_proposal "$pid" "$pidv")")"
+    status="$(runtime_http_status)"
+    case "$status" in
+      200) _graph_sync_status_render "$cid" "$pidv" "$resp" ;;
+      404)
+        # HU-OR-73 E5: «no existe» y «es de otro proyecto» son el MISMO cuerpo, bit a bit.
+        echo "$pidv  DESCONOCIDA para el hub (o es de otro proyecto: son indistinguibles)" ;;
+      *)
+        echo "$pidv  ${st:-?}  (el hub no respondió, HTTP $status: se muestra el último estado conocido)" ;;
+    esac
+  done
+  return $OPS_RC_OK
+}
+
+# _graph_sync_status_render <cid> <proposal_id> <respuesta> — pinta el veredicto y lo persiste
+# en el ledger. La persistencia va aquí y no en el llamador porque el estado del hub SOLO se
+# conoce al leer la respuesta: guardarlo fuera obligaría a re-parsearla.
+_graph_sync_status_render() {
+  local cid="$1" pidv="$2" resp="$3" st reason applied
+  st="$(_graph_sync_out "$resp" status)"
+  reason="$(_graph_sync_out "$resp" reject_reason)"
+  applied="$(_graph_sync_out "$resp" graph_version_applied)"
+  case "$st" in
+    APPROVED)
+      echo "$pidv  APPROVED  (grafo del hub en v${applied:-?})"
+      echo "         nada más que hacer: las historias nuevas entran solas al reparto del claim." ;;
+    REJECTED)
+      echo "$pidv  REJECTED  ${reason:-sin motivo registrado}"
+      echo "         corrige los docs de discovery y vuelve a proponer con \`graph-sync\`." ;;
+    PROPOSED)
+      echo "$pidv  PROPOSED  (esperando aprobación humana en la consola del hub)" ;;
+    *)
+      echo "$pidv  ${st:-?}" ;;
+  esac
+  ops_graph_sync_ledger_upsert "{\"client_event_id\":$(ops_json_str "$cid"),\"status\":$(ops_json_str "${st:-PROPOSED}"),\"reject_reason\":$(ops_json_str "$reason"),\"graph_version_applied\":$(ops_json_str "$applied")}"
+}
+
 # ── status ───────────────────────────────────────────────────────────────────────────
 # Informe local del agente: modo, proyecto (con sus hechos: scaffold/fuente de diseño/
 # tipo/caparazón — la precondición temprana de /build:slice y /build:work la evalúan de
@@ -1044,30 +1490,22 @@ cmd_escalate() {
 }
 
 # ── Helpers comunes de los subcomandos que transicionan ──────────────────────────────
-# _ops_dual_mirror <kind> <payload_json> — en `dual` el fichero es primario: se añade la
-# identidad local al payload y se manda al espejo. Un fallo del espejo NUNCA bloquea:
-# se avisa y se devuelve 0 (queda como discrepancia del comparador, spec §6.1).
+# _ops_dual_mirror <event_type> <payload_json> — en `dual` el fichero es primario: la transición
+# se manda al espejo con el `epic_code` del estado local. Un fallo del espejo NUNCA bloquea: se
+# avisa y se devuelve 0 (queda como discrepancia del comparador, spec §6.1).
+#
+# [EP-OR-17] El `slice_ref` que se inyectaba DENTRO del payload se ha eliminado: los schemas del
+# catálogo son `extra="forbid"` y ese campo era rechazo garantizado. Su información —de qué
+# épica es la transición— es justamente el `epic_code` del SOBRE, que ahora sí viaja donde el
+# hub lo lee.
 _ops_dual_mirror() {
-  local kind="$1" payload="$2" ref pfile rc
-  ref="$(ops_local_slice_ref)"
+  local event_type="$1" payload="$2" epic pfile rc
+  epic="$(ops_local_slice_ref | python3 -c 'import json,sys; print(json.load(sys.stdin).get("epic_code") or "")' 2>/dev/null)"
   pfile="$(ops_tmpjson "$payload")" || return $OPS_RC_OK
-  command -v python3 >/dev/null 2>&1 && python3 - "$pfile" "$ref" <<'PY' 2>/dev/null
-import json,sys
-p,ref=sys.argv[1],sys.argv[2]
-try:
-    d=json.load(open(p))
-except Exception:
-    d={}
-try:
-    d["slice_ref"]=json.loads(ref)
-except Exception:
-    d["slice_ref"]={}
-json.dump(d,open(p,"w"),ensure_ascii=False)
-PY
-  ops_mirror "$kind" "$pfile"
+  ops_mirror "$event_type" "$pfile" "$epic"
   rc=$?
   rm -f "$pfile"
-  [ $rc -eq 0 ] || echo "⚠ transición «${kind}» no espejada (rc $rc): el comparador dual la marcará" >&2
+  [ $rc -eq 0 ] || echo "⚠ transición «${event_type}» no espejada (rc $rc): el comparador dual la marcará" >&2
   return $OPS_RC_OK
 }
 
@@ -1411,7 +1849,9 @@ PY
   fi
   mode="$(ops_mode)"
   if [ "$mode" = "dual" ]; then
-    ops_mirror wiring_checklist_seeded "$pfile" || echo "⚠ siembra de wiring no espejada; el comparador dual la marcará" >&2
+    ops_mirror wiring_checklist_seeded "$pfile" \
+      "$(ops_local_slice_ref | python3 -c 'import json,sys; print(json.load(sys.stdin).get("epic_code") or "")' 2>/dev/null)" \
+      || echo "⚠ siembra de wiring no espejada; el comparador dual la marcará" >&2
     rm -f "$pfile"
     return $OPS_RC_OK
   fi
@@ -1557,6 +1997,8 @@ case "$SUB" in
   propose-epic) cmd_propose_epic "$@"; exit $? ;;
   epic-status) cmd_epic_status "$@"; exit $? ;;
   epic-writeback) cmd_epic_writeback "$@"; exit $? ;;
+  graph-sync) cmd_graph_sync "$@"; exit $? ;;
+  graph-sync-status) cmd_graph_sync_status "$@"; exit $? ;;
   status) cmd_status "$@"; exit $? ;;
   escalate) cmd_escalate "$@"; exit $? ;;
   ""|-h|--help|help) usage; exit $OPS_RC_USAGE ;;