@trycore/spec-build-harness 0.14.1 → 0.15.0

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

@@ -21,6 +21,7 @@ OPS_RC_NO_SLICE=4
 OPS_RC_OFFLINE=5
 OPS_RC_REJECTED=6
 OPS_RC_NO_WORK=7
+OPS_RC_NOT_MIRRORABLE=8
 
 # Tope de texto libre que el cliente manda al servidor (evidencias, notas): el protocolo §8
 # dice que el servidor rechaza payloads sobredimensionados; se trunca aquí, marcándolo.
@@ -40,6 +41,16 @@ OPS_RELEASE_GATES="security smell ux coherence stack_arch integration"
 # (orden estricto, domain.py:400-407) — de aquí salen las cadenas que emite `phase`.
 OPS_SLICE_PHASES="dor change red green refactor smoke api data dod pr"
 
+# Enumeración NORMATIVA de la ingesta espejo (`TIPOS_DE_ESPEJO` del hub, derivada allí de los
+# schemas que heredan de `_TransicionDeEspejo`). Se replica aquí para no gastar una llamada en
+# algo que el hub va a rechazar por elemento — y el test la compara contra esta misma lista, así
+# que ampliarla en el hub obliga a ampliarla aquí (lección de #44: dos listas del mismo hecho
+# divergen tarde o temprano, y la que calla es la que miente).
+# `release_verdict_reported` y `front_integration_reported` NO están, y no es un olvido: no
+# existen en el catálogo del hub. Sus canales de espejo son trabajo hub-side (tipo nuevo con su
+# base `_TransicionDeEspejo` y su rama de reducer), no algo que este cliente pueda arreglar.
+OPS_MIRROR_TYPES="slice_opened phase_advanced phase_reverted gate_verdict wiring_item_updated wiring_checklist_seeded checkpoint_recorded progress_noted handoff_recorded"
+
 # ops_phase_idx <fase> — índice de la fase en OPS_SLICE_PHASES; -1 si no es fase del hub.
 ops_phase_idx() {
   local i=0 p
@@ -112,8 +123,19 @@ ops_path_proposals() { echo "/projects/$1/context/agent-proposals"; }
 # (`EP-XXX`) al aprobar y un humano aprueba: por eso hay una ruta de creación y otra de
 # consulta, y ninguna de publicación. Mismo patrón que las propuestas de asset
 # (`ops_path_proposals`), que es su precedente en este cliente.
-ops_path_epic_proposals() { echo "/projects/$1/epic-proposals"; }
-ops_path_epic_proposal() { echo "/projects/$1/epic-proposals/$2"; }
+# [#70] El carril del AGENTE lleva `/agent/`: `/projects/{id}/epic-proposals` (sin él) es la
+# vista de CONSOLA — GET con JWT de usuario — y responde `405 Allow: GET` a un POST con token
+# de proyecto. Las dos superficies no se comparten por diseño (hub CON-1).
+ops_path_epic_proposals() { echo "/projects/$1/agent/epic-proposals"; }
+ops_path_epic_proposal() { echo "/projects/$1/agent/epic-proposals/$2"; }
+
+# [EP-OR-17] Re-sync del grafo (HU-OR-72/73). El arnés PROPONE el bundle construido desde los
+# docs de discovery, el hub calcula el delta y un HUMANO aprueba en la consola: nada se aplica
+# por esta ruta. Mismo carril `/agent/` que las propuestas de épica y por la misma razón — la
+# ruta sin `/agent/` es la superficie humana (sesión + PDP) y a un bearer de agente le responde
+# 403 auditado, no 405: las dos superficies no se comparten por diseño.
+ops_path_graph_sync_proposals() { echo "/projects/$1/agent/graph-sync-proposals"; }
+ops_path_graph_sync_proposal() { echo "/projects/$1/agent/graph-sync-proposals/$2"; }
 
 ops_mode() { runtime_mode; }
 
@@ -262,39 +284,96 @@ PY
   runtime_outbox_enforce_cap >/dev/null
 }
 
-# ops_mirror <kind> <payload_file> — ingesta espejo del modo `dual` (spec §4.1-D). El
-# fichero local sigue siendo primario: un rechazo del reducer NO bloquea el trabajo, queda
-# como discrepancia del comparador. rc 0 aceptado · 5 no se pudo (red) · 6 rechazado.
+# ops_mirror <event_type> <payload_file> [epic_code] — ingesta espejo del modo `dual`
+# (spec §4.1-D). El fichero local sigue siendo primario: un rechazo del reducer NO bloquea el
+# trabajo, queda como discrepancia del comparador.
+# rc 0 aplicado o duplicado · 5 no se pudo (red, sin epic_code, sin python3) · 6 rechazado
+# · 8 el tipo no es espejable.
+#
+# [EP-OR-17] El cuerpo es `MirrorTransitionsIn`: `{"transitions":[{client_event_id, epic_code,
+# event_type, payload}]}`. El `{kind, payload, origin, occurred_at}` que se mandaba antes no
+# existe en el contrato — el 100 % de lo que el modo dual espejaba era un 422. El `occurred_at`
+# tampoco viaja, y no por descuido: los relojes de cliente entran SOLO por el import; aquí
+# estampa el servidor. El `origin` tampoco: la marca de origen-espejo la pone el hub, y lo que
+# el cliente dijera no elegiría el origen de todos modos.
 ops_mirror() {
-  local kind="$1" pfile="$2" pid body resp status tmp
+  local event_type="$1" pfile="$2" epic_code="${3:-}" pid body resp status tmp
+  case " $OPS_MIRROR_TYPES " in
+    *" $event_type "*) : ;;
+    *)
+      echo "⚠ «${event_type}» está fuera de la enumeración normativa del catálogo de espejo del hub:" >&2
+      echo "  no se envía (viajaría solo para volver rechazado por elemento). Espejables:" >&2
+      echo "  $OPS_MIRROR_TYPES" >&2
+      return $OPS_RC_NOT_MIRRORABLE ;;
+  esac
   pid="$(runtime_field project_id)"
-  [ -n "$pid" ] || return 5
-  command -v python3 >/dev/null 2>&1 || return 5
-  tmp="$(mktemp)" || return 5
-  python3 - "$kind" "$pfile" > "$tmp" <<'PY' 2>/dev/null
-import json,sys,datetime
-kind,pfile=sys.argv[1],sys.argv[2]
+  [ -n "$pid" ] || return $OPS_RC_OFFLINE
+  [ -n "$epic_code" ] || epic_code="$(ops_local_slice_ref | python3 -c 'import json,sys; print(json.load(sys.stdin).get("epic_code") or "")' 2>/dev/null)"
+  if [ -z "$epic_code" ]; then
+    echo "⚠ «${event_type}» no espejado: sin epic_code (el hub lo exige y el lote sería un 422)." >&2
+    echo "  Sale de active_slice.epica del build-state local: abre un slice antes de espejar." >&2
+    return $OPS_RC_OFFLINE
+  fi
+  command -v python3 >/dev/null 2>&1 || return $OPS_RC_OFFLINE
+  tmp="$(mktemp)" || return $OPS_RC_OFFLINE
+  python3 - "$event_type" "$pfile" "$epic_code" > "$tmp" <<'PY' 2>/dev/null
+import json,sys,uuid
+event_type,pfile,epic_code=sys.argv[1],sys.argv[2],sys.argv[3]
 try:
     payload=json.load(open(pfile))
 except Exception:
     payload={}
-print(json.dumps({"kind":kind,"payload":payload,"origin":"mirror",
-                  "occurred_at":datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")},
-                 ensure_ascii=False))
+if not isinstance(payload,dict):
+    payload={}
+print(json.dumps({"transitions":[{"client_event_id":str(uuid.uuid4()),
+                                  "epic_code":epic_code,
+                                  "event_type":event_type,
+                                  "payload":payload}]},ensure_ascii=False))
 PY
   body="$(cat "$tmp" 2>/dev/null)"
   rm -f "$tmp"
-  [ -n "$body" ] || return 5
+  [ -n "$body" ] || return $OPS_RC_OFFLINE
   resp="$(runtime_post "$(ops_path_mirror "$pid")" "$body")"
   status="$(runtime_http_status)"
   case "$status" in
-    200|201|202) return 0 ;;
+    200|201|202) _ops_mirror_report "$event_type" "$resp" ;;
     409|422)
-      echo "⚠ el espejo rechazó «${kind}»: $resp" >&2
+      # 409 = el cutover apagó la ingesta espejo para este proyecto; 422 = el lote no cumple el
+      # borde. Los dos son del LOTE entero, no de un elemento: no hay reporte que leer.
+      echo "⚠ el espejo rechazó «${event_type}» (HTTP $status): $resp" >&2
       echo "  (queda como discrepancia del comparador dual; el trabajo local NO se bloquea)" >&2
-      return 6 ;;
-    *) return 5 ;;
+      return $OPS_RC_REJECTED ;;
+    *) return $OPS_RC_OFFLINE ;;
+  esac
+}
+
+# _ops_mirror_report <event_type> <respuesta> — lee el reporte POR ELEMENTO (HU-OR-56 E3).
+# rc 0 aplicado o duplicado · 6 rechazado, con el motivo del hub a la vista: volcar el cuerpo
+# crudo escondía justo la frase que dice qué hay que arreglar.
+_ops_mirror_report() {
+  local event_type="$1" reason
+  command -v python3 >/dev/null 2>&1 || return $OPS_RC_OK
+  reason="$(printf '%s' "$2" | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+    rs=d.get("results") or []
+    sys.stdout.write(next((r.get("reason") or "rechazado sin motivo registrado")
+                          for r in rs if r.get("status")=="rejected"))
+except Exception:
+    pass
+' 2>/dev/null)"
+  [ -n "$reason" ] || return $OPS_RC_OK
+  echo "⚠ el espejo rechazó «${event_type}»: $reason" >&2
+  case "$reason" in
+    *"no existe en el grafo"*)
+      # Este es EL rechazo del piloto: el grafo del hub se quedó en la foto del import inicial
+      # y toda transición de una épica posterior rebota. Ahora hay una salida que ofrecer.
+      echo "  El grafo del hub no conoce esa épica. Propón el re-sync con" >&2
+      echo "  \`slice-ops.sh graph-sync --file epics.json\` y pide su aprobación en la consola." >&2 ;;
   esac
+  echo "  (queda como discrepancia del comparador dual; el trabajo local NO se bloquea)" >&2
+  return $OPS_RC_REJECTED
 }
 
 # ── Ledger local de propuestas de épica [#62] ────────────────────────────────────────
@@ -305,11 +384,13 @@ PY
 # instante); `proposal_id` llega después, con el ack, y puede no llegar nunca (offline).
 ops_epic_ledger_path() { echo "$(config_root)/.claude/state/epic-proposals.json"; }
 
-# ops_epic_ledger_read — imprime {"proposals":[…]}; nunca lanza.
-ops_epic_ledger_read() {
-  local f; f="$(ops_epic_ledger_path)"
+# _ops_ledger_read <fichero> — imprime {"proposals":[…]}; nunca lanza.
+# [EP-OR-17] Base común del ledger de propuestas de épica y del de re-sync del grafo: son la
+# misma estructura con otra ruta, y duplicar 60 líneas de python3 garantizaba que una de las
+# dos copias se quedara atrás.
+_ops_ledger_read() {
   command -v python3 >/dev/null 2>&1 || { echo '{"proposals":[]}'; return; }
-  python3 - "$f" <<'PY' 2>/dev/null || echo '{"proposals":[]}'
+  python3 - "$1" <<'PY' 2>/dev/null || echo '{"proposals":[]}'
 import json,sys
 try:
     d=json.load(open(sys.argv[1]))
@@ -320,12 +401,11 @@ except Exception:
 PY
 }
 
-# ops_epic_ledger_upsert <entrada-json> — upsert por client_event_id: las claves que la
+# _ops_ledger_upsert <fichero> <entrada-json> — upsert por client_event_id: las claves que la
 # entrada NO menciona se conservan (así un `epic-status` puede fijar el estado sin borrar el
 # borrador que guardó `propose-epic`). Escritura atómica. rc 0/1.
-ops_epic_ledger_upsert() {
-  local entry="$1" f
-  f="$(ops_epic_ledger_path)"
+_ops_ledger_upsert() {
+  local f="$1" entry="$2"
   mkdir -p "$(dirname "$f")"
   command -v python3 >/dev/null 2>&1 || return 1
   python3 - "$f" "$entry" <<'PY' 2>/dev/null || return 1
@@ -348,7 +428,7 @@ for i,p in enumerate(ps):
 else:
     ps.append(e)
 dirn=os.path.dirname(path) or "."
-fd,tmp=tempfile.mkstemp(dir=dirn,prefix=".epic-proposals.",suffix=".tmp")
+fd,tmp=tempfile.mkstemp(dir=dirn,prefix=".ledger.",suffix=".tmp")
 try:
     with os.fdopen(fd,"w") as out:
         json.dump({"proposals":ps},out,indent=2,ensure_ascii=False); out.flush(); os.fsync(out.fileno())
@@ -360,6 +440,37 @@ except Exception:
 PY
 }
 
+ops_epic_ledger_read() { _ops_ledger_read "$(ops_epic_ledger_path)"; }
+ops_epic_ledger_upsert() { _ops_ledger_upsert "$(ops_epic_ledger_path)" "$1"; }
+
+# ── Ledger local del re-sync del grafo [EP-OR-17] ────────────────────────────────────
+# Fichero PROPIO, no una sección del de épicas: un re-sync no es una propuesta de épica, y
+# mezclarlos haría que `epic-status` hablara de grafos y `graph-sync-status` de épicas.
+ops_graph_sync_ledger_path() { echo "$(config_root)/.claude/state/graph-sync-proposals.json"; }
+ops_graph_sync_ledger_read() { _ops_ledger_read "$(ops_graph_sync_ledger_path)"; }
+ops_graph_sync_ledger_upsert() { _ops_ledger_upsert "$(ops_graph_sync_ledger_path)" "$1"; }
+
+# ops_graph_sync_cid — `client_event_id` DETERMINISTA de la próxima propuesta de re-sync:
+# `<agent_key>:graph-sync:<n>`, con n = entradas del ledger + 1.
+#
+# Determinista es el punto: el reintento tras un 409 de grafo rancio reusa exactamente este
+# cid y el hub deduplica, en vez de acabar con dos propuestas del mismo grafo esperando
+# aprobación humana. El contrato acota el campo a 64 caracteres, así que una `agent_key` larga
+# se sustituye por su sha256 truncado — sigue siendo estable para el mismo agente, que es lo
+# único que la idempotencia necesita.
+ops_graph_sync_cid() {
+  local ak n
+  ak="$(runtime_field agent_key)"
+  [ -n "$ak" ] || ak="agente"
+  n="$(ops_graph_sync_ledger_read | python3 -c 'import json,sys; print(len(json.load(sys.stdin).get("proposals") or []) + 1)' 2>/dev/null)"
+  case "$n" in ''|*[!0-9]*) n=1 ;; esac
+  if [ "${#ak}" -gt 30 ]; then
+    ak="$(printf '%s' "$ak" | python3 -c 'import hashlib,sys; print(hashlib.sha256(sys.stdin.read().encode()).hexdigest()[:16])' 2>/dev/null)"
+    [ -n "$ak" ] || ak="agente"
+  fi
+  echo "${ak}:graph-sync:${n}"
+}
+
 # ops_epic_ack_read <client_event_id> — el ack que dejó el carril directo, o "".
 ops_epic_ack_read() {
   local f; f="$(runtime_outbox_dir)/acks/$1.json"

package/hooks/build/release-ops.sh

@@ -35,7 +35,7 @@ _rel_evidence_json() {
 
 # ── verdict ──────────────────────────────────────────────────────────────────────────
 cmd_verdict() {
-  local line="${1:-}" gate="${2:-}" estado="${3:-}" ev="" evfile="" mode payload resp status pfile rel_status closed_by
+  local line="${1:-}" gate="${2:-}" estado="${3:-}" ev="" evfile="" mode payload resp status rel_status closed_by
   if [ -z "$line" ] || [ -z "$gate" ] || [ -z "$estado" ]; then usage; return $OPS_RC_USAGE; fi
   shift 3
   while [ $# -gt 0 ]; do
@@ -59,9 +59,13 @@ cmd_verdict() {
   [ "$mode" = "legacy" ] && { echo "LEGACY: escribe el gate en releases[] del fichero"; return $OPS_RC_LEGACY; }
   payload="{\"release_line\":$(ops_json_str "$line"),\"gate\":$(ops_json_str "$gate"),\"status\":$(ops_json_str "$estado"),\"verdict\":$(ops_json_str "$(printf %s "$estado" | tr a-z A-Z)"),\"evidence\":$(_rel_evidence_json "$ev" "$evfile")}"
   if [ "$mode" = "dual" ]; then
-    pfile="$(ops_tmpjson "$payload")" || return $OPS_RC_OFFLINE
-    ops_mirror release_verdict_reported "$pfile" || echo "⚠ veredicto de release no espejado; el comparador dual lo marcará" >&2
-    rm -f "$pfile"
+    # [EP-OR-17] El hub NO tiene canal de espejo para los veredictos de release:
+    # `release_verdict_reported` no existe en su catálogo de eventos (`TIPOS_DE_ESPEJO` solo
+    # cubre transiciones de slice) y su superficie síncrona es de gobierno humano. Mandarlo era
+    # gastar una llamada para recibir un rechazo por elemento y un aviso genérico que mandaba a
+    # revisar una red que funcionaba. Se dice lo que pasa y se sigue: el fichero es primario.
+    echo "DUAL: veredicto anotado en local. El hub todavía no espeja veredictos de release"
+    echo "(no hay tipo en su catálogo): quedará reflejado al pasar a modo \`runtime\`."
     return $OPS_RC_OK
   fi
   resp="$(runtime_post "$(ops_path_release_verdicts "$(ops_urlenc "$line")")" "$payload")"
@@ -135,7 +139,7 @@ HINT
 # distinto): reporta la integración de SU miembro. Planificar, abrir, drenar y cerrar el
 # front siguen siendo humanos.
 cmd_front_integration() {
-  local front="${1:-}" merge="" resmoke="" ev="" evfile="" mode akey payload resp status pfile
+  local front="${1:-}" merge="" resmoke="" ev="" evfile="" mode akey payload resp status
   [ -n "$front" ] || { usage; return $OPS_RC_USAGE; }
   shift
   while [ $# -gt 0 ]; do
@@ -159,9 +163,10 @@ cmd_front_integration() {
   [ "$mode" = "legacy" ] && { echo "LEGACY: actualiza parallel_front.members[] en el fichero"; return $OPS_RC_LEGACY; }
   payload="{\"merge_status\":$(ops_json_str "$merge"),\"re_smoke\":{\"status\":$(ops_json_str "$resmoke"),\"evidence\":$(_rel_evidence_json "$ev" "$evfile")}}"
   if [ "$mode" = "dual" ]; then
-    pfile="$(ops_tmpjson "$payload")" || return $OPS_RC_OFFLINE
-    ops_mirror front_integration_reported "$pfile" || echo "⚠ integración de front no espejada; el comparador dual la marcará" >&2
-    rm -f "$pfile"
+    # Mismo caso que los veredictos de release: `front_integration_reported` no existe en el
+    # catálogo del hub y el agregado `front` no entra por la ingesta espejo.
+    echo "DUAL: integración anotada en local. El hub todavía no espeja integraciones de front"
+    echo "(no hay tipo en su catálogo): quedará reflejada al pasar a modo \`runtime\`."
     return $OPS_RC_OK
   fi
   akey="$(runtime_field agent_key)"