@trycore/spec-build-harness 0.8.4 → 0.10.0

package/hooks/build/slice-ops.sh

@@ -0,0 +1,877 @@
+#!/usr/bin/env bash
+# slice-ops.sh — operaciones de dominio del INNER LOOP que conducen las skills
+# [EP-OR-08-C]. NO es un hook registrado (mismo estatus que context-sync.sh): lo invocan
+# `building-a-slice`, los comandos /build:* y los agentes, UNA invocación por transición.
+#
+#   uso: slice-ops.sh <subcomando> [opciones]
+#   subcomandos IMPLEMENTADOS (los 13 del plan): mode | claim | next-step | gate | submit |
+#                archive | wiring | progress | checkpoint | fact | propose-asset | 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
+# escribe en stdout lo que la skill debe mostrar. Fail-open: el trabajo local nunca se
+# bloquea por el runtime (RNF-6).
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/lib/runtime-ops.sh"
+
+usage() {
+  cat >&2 <<'USAGE'
+uso: slice-ops.sh <subcomando> [opciones]
+
+  mode                                          imprime legacy|dual|runtime
+  claim [--epic EP-XXX]                         reclama trabajo (solo modo runtime)
+  next-step                                     deriva la siguiente acción desde la caché
+  gate <nombre> <pass|fail|na> [--evidence «texto» | --evidence-file F]
+                                                reporta un veredicto del slice (hecho medido)
+  submit [--pr-url U] [--openspec-change C]     entrega el slice
+  archive [--pr-url U] [--openspec-change C] [--epic EP-XXX]
+                                                archiva el slice (siempre por la cola)
+  wiring seed --file items.json                 siembra el checklist de cableado (failing)
+  wiring update <item_id> <passing|failing> [--kind K] [--ref R] [--evidence-file F]
+  progress «nota» | --file F                    nota de progreso (bitácora = event stream)
+  checkpoint [--note «t» | --note-file F]        continuidad tras una caída
+  fact <scaffold-confirmed|design-source|project-kind|foundation|harness-phase> …
+                                                reporta un hecho de proyecto confirmado
+  propose-asset --type-key K --path P --content-file F
+  status [--no-refresh]                         informe local del agente
+  escalate «razón» | --file F [--gate G]        registra un bloqueo (la decisión es humana)
+
+códigos de salida: 0 ok · 2 uso · 3 legacy · 4 sin slice · 5 offline · 6 rechazado · 7 sin trabajo
+USAGE
+}
+
+# ── claim ────────────────────────────────────────────────────────────────────────────
+# Protocolo §3: siempre POST (el GET no acepta el reporte de hashes); regla 1: no se abre
+# trabajo con contexto viejo, así que se sincroniza ANTES; los 409 se distinguen por su
+# CUERPO (spec §3.1 rev. 2), no por el status.
+
+# _claim_field <json> <clave> — lee una clave de primer nivel de una respuesta JSON.
+_claim_field() {
+  command -v python3 >/dev/null 2>&1 || { echo ""; return; }
+  printf '%s' "$1" | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+    v=d.get(sys.argv[1]) if isinstance(d,dict) else None
+    print(v if isinstance(v,str) else "")
+except Exception:
+    print("")
+' "$2" 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; }
+  printf '%s' "$1" | python3 - <<'PY' 2>/dev/null || echo "$1"
+import json,sys
+try:
+    d=json.load(sys.stdin)
+except Exception:
+    sys.exit(1)
+if not isinstance(d,dict):
+    sys.exit(1)
+g=d.get("gates") or {}
+abiertos=[k for k,v in g.items() if v is False]
+lease=d.get("lease") or {}
+cp=d.get("checkpoint")
+print("slice:        %s (%s %s)" % (d.get("slice_id"), d.get("epic_code"), d.get("epic_title") or ""))
+print("fase:         %s" % d.get("phase"))
+print("gates abiertos: %s" % (", ".join(abiertos) if abiertos else "ninguno"))
+print("rama base:    %s" % d.get("branch_base"))
+print("change:       %s" % d.get("openspec_change"))
+print("docs:         %s" % d.get("docs_ref"))
+print("historias:    %s" % ", ".join(d.get("stories") or []))
+print("lease:        expira %s (ttl %ss)" % (lease.get("expires_at"), lease.get("ttl_s")))
+if cp:
+    print("CHECKPOINT:   rama %s commit %s — CONTINÚA desde aquí, jamás reinicies (protocolo §3 regla 2)"
+          % (cp.get("branch"), cp.get("commit_sha")))
+PY
+}
+
+# _claim_once <epic> — una llamada. rc 20 = reintentable (drift|contention), resto = final.
+_claim_once() {
+  local epic="$1" hashes body resp status reason
+  hashes="$(ops_context_hashes)"
+  body="{\"context_hashes\":$hashes"
+  [ -n "$epic" ] && body="$body,\"epic_code\":$(ops_json_str "$epic")"
+  body="$body}"
+  resp="$(runtime_post "$OPS_PATH_CLAIM" "$body")"
+  status="$(runtime_http_status)"
+  case "$status" in
+    200)
+      agent_context_fetch_and_cache || \
+        echo "⚠ claim aceptado, pero /agent/context no respondió: se sigue con la caché anterior" >&2
+      _claim_render "$resp"
+      return $OPS_RC_OK ;;
+    204)
+      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)"
+      case "$reason" in
+        drift|contention)
+          echo "⚠ 409 ($reason): reintentable" >&2
+          return 20 ;;
+        context_unresolvable)
+          echo "⛔ 409 contexto irresoluble — NO reintentar: $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 "  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
+          return $OPS_RC_REJECTED ;;
+      esac ;;
+    401|403)
+      echo "⛔ token inválido o revocado ($status): pide un token nuevo al ADMIN del proyecto." >&2
+      echo "  Los guards siguen operando con el último lock; el trabajo local no se detiene." >&2
+      return $OPS_RC_REJECTED ;;
+    422)
+      echo "⛔ 422 el servidor rechazó el claim: $resp — no reintentar." >&2
+      return $OPS_RC_REJECTED ;;
+    000)
+      echo "OFFLINE: runtime inalcanzable; se sigue con la caché local (RNF-6)" >&2
+      return $OPS_RC_OFFLINE ;;
+    *)
+      echo "⚠ respuesta inesperada del claim ($status): $resp" >&2
+      return $OPS_RC_OFFLINE ;;
+  esac
+}
+
+cmd_claim() {
+  local epic="" mode expected rc
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --epic) epic="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  mode="$(ops_mode)"
+  if [ "$mode" = "legacy" ]; then
+    echo "LEGACY: el fichero es primario; abre el slice con el protocolo de references/state-protocol.md"
+    return $OPS_RC_LEGACY
+  fi
+  if [ "$mode" = "dual" ]; then
+    echo "DUAL_NO_CLAIM: en dual el slice lo decide el fichero (spec §6.1)."
+    echo "Abre el slice en local y reporta cada transición con los demás subcomandos (espejo)."
+    return $OPS_RC_LEGACY
+  fi
+  # Contexto primero (protocolo §3 regla 1). context-sync.sh es fail-open: si no puede,
+  # sale 0 y deja el lock anterior — el claim seguirá y el servidor detectará el drift.
+  expected="$(projection_get context.manifest_hash "")"
+  [ -n "$expected" ] || expected="$(runtime_field manifest_hash)"
+  bash "$HERE/context-sync.sh" "$expected" >/dev/null 2>&1
+  _claim_once "$epic"
+  rc=$?
+  if [ $rc -eq 20 ]; then
+    # Drift o contención: reintentar EXACTAMENTE una vez (protocolo §7). Pasar "" a
+    # context-sync.sh NO fuerza nada: su propio fallback (`EXPECTED="$(runtime_field
+    # manifest_hash)"`) recae en la caché de credenciales, que en el escenario de drift
+    # YA coincide con el lock local (eso es precisamente lo que distingue "drift" del
+    # estado real del servidor) — el primer guard de context-sync.sh corta en seco y
+    # nunca llega a preguntarle nada al servidor. Se refresca antes el estado REAL
+    # (GET /agent/context, que sí toca la red) y se usa SU manifest_hash como EXPECTED:
+    # si el drift es real, difiere del lock y el guard deja pasar el GET del manifiesto.
+    agent_context_fetch_and_cache >/dev/null 2>&1
+    expected="$(projection_get context.manifest_hash "")"
+    bash "$HERE/context-sync.sh" "$expected" >/dev/null 2>&1
+    _claim_once "$epic"
+    rc=$?
+    if [ $rc -eq 20 ]; then
+      echo "otro agente tomó la tarea; pide la siguiente"
+      return $OPS_RC_NO_WORK
+    fi
+  fi
+  return $rc
+}
+
+# ── next-step ────────────────────────────────────────────────────────────────────────
+# El servidor entrega hechos; el PASO lo deriva el cliente (spec §2, invierte el plan §1.3).
+# Prioridad determinista, la primera que aplique.
+cmd_next_step() {
+  local sid proj tmp_script
+  sid="$(ops_slice_id)"
+  if [ -z "$sid" ]; then
+    echo "sin slice activo: reclama trabajo (\`slice-ops.sh claim\`) o abre uno por DoR"
+    return $OPS_RC_NO_SLICE
+  fi
+  command -v python3 >/dev/null 2>&1 || { echo "continúa el pipeline por la fase del slice"; return $OPS_RC_OK; }
+  proj="$(runtime_projection_read)"
+  tmp_script="$(mktemp)"
+  cat > "$tmp_script" <<'PY'
+import json,sys
+orden=sys.argv[1].split()
+try:
+    d=json.load(sys.stdin)
+except Exception:
+    d={}
+sl=d.get("active_slice") or {}
+hint=sl.get("resume_hint")
+failing=sl.get("wiring_failing") or []
+subs=sl.get("sub_slices_pending") or []
+gates=sl.get("gates") or {}
+if hint:
+    print("resume_hint: %s" % hint)
+elif failing:
+    it=failing[0]
+    print("cablear el item de wiring «%s» (%s) con prueba REAL ejecutada; no lo marques passing por inspección"
+          % (it.get("item_id"), it.get("kind")))
+elif subs:
+    print("construir el siguiente sub-slice: %s (journey_smoke verde antes de pasar al siguiente)" % subs[0])
+else:
+    abierto=next((g for g in orden if gates.get(g) is False), None)
+    if abierto:
+        print("cerrar el gate «%s» (fase %s)" % (abierto, sl.get("phase")))
+    else:
+        print("todos los gates conocidos están cerrados: abre el PR, archiva el change y reporta submit")
+PY
+  echo "$proj" | python3 "$tmp_script" "$OPS_SLICE_GATES" 2>/dev/null || echo "continúa el pipeline por la fase del slice"
+  rm -f "$tmp_script"
+}
+
+# ── fact ─────────────────────────────────────────────────────────────────────────────
+# Hechos de PROYECTO (spec §4.1-B): dos ya persisten en el runtime con superficie admin
+# (`scaffold_confirmed`, `design_source_*`) y ganan evento + proyección; tres se crean
+# completos (`project_kind`, `foundation`, `harness_phase`). Todos son de ámbito proyecto:
+# se encolan SIN `slice_id` (el servidor los admite así, spec §3.1 rev. 3).
+# La CONFIRMACIÓN sigue siendo humana: este subcomando REPORTA lo que el humano confirmó.
+cmd_fact() {
+  local hecho="${1:-}" mode
+  [ -n "$hecho" ] && shift
+  mode="$(ops_mode)"
+  if [ "$mode" = "legacy" ]; then
+    echo "LEGACY: escribe el hecho en el fichero (scaffold/design_source/project_kind/foundation)"
+    return $OPS_RC_LEGACY
+  fi
+  case "$hecho" in
+    scaffold-confirmed) _fact_scaffold "$@" ;;
+    design-source) _fact_design_source "$@" ;;
+    project-kind) _fact_project_kind "$@" ;;
+    foundation) _fact_foundation "$@" ;;
+    harness-phase) _fact_harness_phase "$@" ;;
+    *) echo "uso: slice-ops.sh fact <scaffold-confirmed|design-source|project-kind|foundation|harness-phase> [opciones]" >&2
+       return $OPS_RC_USAGE ;;
+  esac
+}
+
+# _ops_emit_event <tipo> <payload_json> [slice_id] — evento genérico de dominio: espejo en
+# dual (mejor esfuerzo, spec §4.1-D) o cola en runtime (spec §3.1). El slice_id es opcional
+# (los hechos de PROYECTO se encolan sin él, spec §3.1 rev. 3; una escalada de slice sí lo
+# lleva). Devuelve $OPS_RC_OFFLINE si el runtime no pudo aceptar el evento (outbox no
+# 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
+  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
+    rm -f "$pfile"
+    return $OPS_RC_OK
+  fi
+  if ! ops_enqueue_from_file "$tipo" "$pfile" "$sid"; then
+    rm -f "$pfile"
+    return $OPS_RC_OFFLINE
+  fi
+  rm -f "$pfile"
+  return $OPS_RC_OK
+}
+
+# _fact_emit <tipo> <payload_json> — un hecho de PROYECTO (sin slice_id): mismo contrato de
+# _ops_emit_event, con el aviso de fallo y el mensaje de éxito que esperan las skills.
+_fact_emit() {
+  local tipo="$1" payload="$2"
+  if ! _ops_emit_event "$tipo" "$payload" ""; then
+    echo "⚠ hecho \"$tipo\" no se pudo encolar (outbox no escribible u otro fallo local)" >&2
+    return $OPS_RC_OFFLINE
+  fi
+  [ "$(ops_mode)" = "runtime" ] && echo "hecho de proyecto \"$tipo\" encolado"
+  return $OPS_RC_OK
+}
+
+_fact_scaffold() {
+  local by="" notes=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --by) by="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --notes) notes="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  [ -n "$by" ] || { echo "⛔ falta --by: el scaffold lo confirma una PERSONA, no el modelo" >&2; return $OPS_RC_REJECTED; }
+  _fact_emit scaffold_confirmed "{\"confirmed\":true,\"confirmed_by\":$(ops_json_str "$by"),\"notes\":$(ops_json_str "$notes")}"
+}
+
+_fact_design_source() {
+  local applies="" source="" confirmed="false" by="" notes=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --applies) applies="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --source) source="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --confirmed) confirmed="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --by) by="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --notes) notes="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  case "$applies" in true|false) : ;; *) echo "⛔ --applies debe ser true|false" >&2; return $OPS_RC_REJECTED ;; esac
+  case "$confirmed" in true|false) : ;; *) echo "⛔ --confirmed debe ser true|false" >&2; return $OPS_RC_REJECTED ;; esac
+  if [ "$confirmed" = "true" ] && [ -z "$by" ]; then
+    echo "⛔ falta --by: la fuente de diseño la confirma una PERSONA" >&2
+    return $OPS_RC_REJECTED
+  fi
+  _fact_emit design_source_declared "{\"applies\":$applies,\"source\":$(ops_json_str "$source"),\"confirmed\":$confirmed,\"confirmed_by\":$(ops_json_str "$by"),\"notes\":$(ops_json_str "$notes")}"
+}
+
+_fact_project_kind() {
+  local kind="${1:-}" src="human"
+  [ -n "$kind" ] && shift
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --source) src="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  case "$kind" in greenfield|brownfield) : ;; *) echo "⛔ project-kind debe ser greenfield|brownfield" >&2; return $OPS_RC_REJECTED ;; esac
+  case "$src" in auto|human) : ;; *) echo "⛔ --source debe ser auto|human" >&2; return $OPS_RC_REJECTED ;; esac
+  _fact_emit project_kind_declared "{\"project_kind\":$(ops_json_str "$kind"),\"source\":$(ops_json_str "$src")}"
+}
+
+_fact_foundation() {
+  local required="" epic="" cfile="" checklist="[]"
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --required) required="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --epic) epic="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --checklist-file) cfile="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  case "$required" in true|false) : ;; *) echo "⛔ --required debe ser true|false" >&2; return $OPS_RC_REJECTED ;; esac
+  if [ -n "$cfile" ] && [ -f "$cfile" ] && command -v python3 >/dev/null 2>&1; then
+    checklist="$(python3 -c '
+import json,sys
+try:
+    d=json.load(open(sys.argv[1]))
+except Exception:
+    d=[]
+print(json.dumps(d if isinstance(d,list) else [], ensure_ascii=False))' "$cfile" 2>/dev/null || echo "[]")"
+  fi
+  _fact_emit foundation_declared "{\"required\":$required,\"epic\":$(ops_json_str "$epic"),\"checklist\":$checklist}"
+}
+
+_fact_harness_phase() {
+  local fase="${1:-}"
+  case "$fase" in authoring|building) : ;; *) echo "⛔ harness-phase debe ser authoring|building" >&2; return $OPS_RC_REJECTED ;; esac
+  _fact_emit harness_phase_changed "{\"harness_phase\":$(ops_json_str "$fase")}"
+}
+
+# ── propose-asset ────────────────────────────────────────────────────────────────────
+# Un agente JAMÁS publica contexto (protocolo §6): propone contra la superficie de agente
+# `…/context/agent-proposals` (no la humana `…/context/proposals`) y un ADMIN publica.
+cmd_propose_asset() {
+  local type_key="" path="" cfile="" mode pid body resp status
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --type-key) type_key="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --path) path="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --content-file) cfile="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  if [ -z "$type_key" ] || [ -z "$path" ] || [ -z "$cfile" ]; then
+    echo "uso: slice-ops.sh propose-asset --type-key K --path P --content-file F" >&2
+    return $OPS_RC_USAGE
+  fi
+  [ -f "$cfile" ] || { echo "⛔ no existe el fichero de contenido: $cfile" >&2; return $OPS_RC_USAGE; }
+  mode="$(ops_mode)"
+  [ "$mode" = "legacy" ] && { echo "LEGACY: el documento queda en git; no hay plano de contexto que proponer"; return $OPS_RC_LEGACY; }
+  pid="$(runtime_field project_id)"
+  [ -n "$pid" ] || { echo "⛔ sin project_id en runtime.credentials: corre \`trycore-build init\`" >&2; return $OPS_RC_REJECTED; }
+  # El contenido puede ser largo: se serializa por fichero (nunca por argv) y el body sale
+  # por `curl --data-binary @fichero` dentro de runtime_post.
+  body="{\"path\":$(ops_json_str "$path"),\"type_key\":$(ops_json_str "$type_key"),\"content\":$(ops_json_str_file "$cfile" 200000)}"
+  resp="$(runtime_post "$(ops_path_proposals "$pid")" "$body")"
+  status="$(runtime_http_status)"
+  case "$status" in
+    200|201|202)
+      echo "propuesta creada: $resp"
+      echo "El agente NO publica contexto: la revisa y publica un ADMIN en la consola del hub."
+      return $OPS_RC_OK ;;
+    422)
+      echo "⛔ 422 la propuesta no valida contra el schema del tipo \"$type_key\": $resp" >&2
+      return $OPS_RC_REJECTED ;;
+    401|403)
+      echo "⛔ token inválido o sin permiso para proponer ($status): habla con el ADMIN." >&2
+      return $OPS_RC_REJECTED ;;
+    *)
+      echo "OFFLINE: no se pudo proponer el asset (status $status). El documento queda en git; reintenta al reconectar." >&2
+      return $OPS_RC_OFFLINE ;;
+  esac
+}
+
+# ── 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
+# aquí, no leen la caché a mano), slice, gates, wiring, contexto, lease y cola.
+# Es INFORMATIVO: rc 0 siempre, pase lo que pase (lo consume /build:status).
+cmd_status() {
+  local refresh=1 mode sid pend lock age
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --no-refresh) refresh=0; shift ;;
+      *) shift ;;
+    esac
+  done
+  mode="$(ops_mode)"
+  echo "modo:         $mode"
+  if [ "$mode" = "legacy" ]; then
+    echo "estado:       el fichero .claude/state/build-state.json es la fuente de verdad (v0.8.5)"
+    echo "runtime:      sin credenciales o modo legacy: no hay nada que consultar"
+    return $OPS_RC_OK
+  fi
+  [ "$refresh" = 1 ] && { agent_context_fetch_and_cache >/dev/null 2>&1 || echo "aviso:        no se pudo refrescar /agent/context (se muestra la caché)"; }
+  echo "proyecto:     $(runtime_field project_id)  ·  agente: $(runtime_field agent_key)"
+  echo "hechos:       scaffold_confirmed=$(projection_get project.scaffold_confirmed false)  ·  design_source_confirmed=$(projection_get project.design_source_confirmed false) (aplica=$(projection_get project.design_source_applies false))  ·  project_kind=$(projection_get project.project_kind "?")  ·  foundation_done=$(projection_get project.foundation_done false)"
+  sid="$(ops_slice_id)"
+  if [ -z "$sid" ]; then
+    echo "slice:        ninguno reclamado"
+  else
+    echo "slice:        $sid  ·  $(projection_get active_slice.epic_code "?")  ·  fase $(projection_get active_slice.phase "?")"
+    echo "gates:        $(projection_get active_slice.gates '{}')"
+    echo "wiring:       $(projection_get active_slice.wiring_failing '[]')"
+    echo "rama:         $(projection_get active_slice.branch "?")  ·  change: $(projection_get active_slice.openspec_change "?")"
+  fi
+  lock="$(runtime_lock_manifest_hash)"
+  age="$(projection_age_seconds)"
+  if projection_is_stale; then
+    echo "contexto:     $lock  ⚠ proyección sin refrescar (${age}s)"
+  else
+    echo "contexto:     $lock  ✓ v$(projection_get context.version "?") (${age}s)"
+  fi
+  echo "lease:        expira $(projection_get lease.expires_at "?")"
+  if [ -f "$(config_root)/.claude/state/heartbeat-status.json" ]; then
+    grep -q '"lease_lost": *true' "$(config_root)/.claude/state/heartbeat-status.json" 2>/dev/null \
+      && echo "              ⚠ lease perdido: haz checkpoint y vuelve a reclamar"
+  fi
+  pend="$(find "$(runtime_outbox_dir)" -maxdepth 1 -name '*.json' ! -name '.dispatch-state.json' 2>/dev/null | wc -l | tr -d ' ')"
+  echo "cola:         $pend evento(s) pendiente(s) de despacho"
+  echo "nudges:       $(projection_get nudges '[]')"
+  return $OPS_RC_OK
+}
+
+# ── helpers para escalate ────────────────────────────────────────────────────────────
+
+# _ops_evidence_json <texto> <fichero> — evidencia para escalate (texto preferentemente,
+# fichero si es grande).
+_ops_evidence_json() {
+  local txt="$1" file="$2"
+  if [ -n "$file" ]; then
+    ops_json_str_file "$file"
+  else
+    ops_json_str "$txt"
+  fi
+}
+
+# ── escalate ─────────────────────────────────────────────────────────────────────────
+# Reportar un bloqueo es acto de agente; DECIDIR qué hacer con él es humano (spec §2).
+# El evento deja el rastro en el runtime; la resolución se pide por el canal humano.
+# La nota de gobierno SOLO se imprime si el evento de verdad quedó registrado (mismo patrón
+# de fallo que _fact_emit): un agente jamás debe creer que escaló algo que se perdió.
+cmd_escalate() {
+  local razon="" file="" gate="" mode sid payload
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --file) file="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --gate) gate="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) [ -z "$razon" ] && razon="$1"; shift ;;
+    esac
+  done
+  if [ -z "$razon" ] && [ -z "$file" ]; then
+    echo "uso: slice-ops.sh escalate «razón» | --file F [--gate G]" >&2
+    return $OPS_RC_USAGE
+  fi
+  mode="$(ops_mode)"
+  if [ "$mode" = "legacy" ]; then
+    echo "LEGACY: no hay runtime donde registrar la escalada; anótala en el PR y habla con el equipo"
+    return $OPS_RC_LEGACY
+  fi
+  payload="{\"reason\":$(_ops_evidence_json "$razon" "$file"),\"gate\":$(ops_json_str "$gate"),\"phase\":$(ops_json_str "$(projection_get active_slice.phase "")")}"
+  sid="$(ops_slice_id)"
+  if ! _ops_emit_event escalation_raised "$payload" "$sid"; then
+    echo "⚠ la escalada no se pudo registrar (outbox no escribible u otro fallo local): repórtala por el PR mientras tanto" >&2
+    return $OPS_RC_OFFLINE
+  fi
+  [ "$mode" = "runtime" ] && echo "escalada registrada (evento encolado)"
+  echo "La DECISIÓN es humana (gobierno, spec §2): recortar, diferir o desbloquear lo acuerda el equipo"
+  echo "en la consola del hub o en el PR. El arnés no decide por ti ni degrada el alcance."
+  return $OPS_RC_OK
+}
+
+# ── 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() {
+  local kind="$1" payload="$2" ref pfile rc
+  ref="$(ops_local_slice_ref)"
+  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"
+  rc=$?
+  rm -f "$pfile"
+  [ $rc -eq 0 ] || echo "⚠ transición «${kind}» no espejada (rc $rc): el comparador dual la marcará" >&2
+  return $OPS_RC_OK
+}
+
+# _ops_evidence_json — evidencia por fichero (preferida) o por texto corto.
+_ops_evidence_json() {
+  local ev="$1" evfile="$2"
+  if [ -n "$evfile" ]; then ops_json_str_file "$evfile"; else ops_json_str "$ev"; fi
+}
+
+# _ops_require_slice — id del slice activo o rc 4 con mensaje accionable.
+_ops_require_slice() {
+  local sid
+  sid="$(ops_slice_id)"
+  if [ -z "$sid" ]; then
+    echo "⛔ no hay slice activo en la caché de proyección: reclama primero (\`slice-ops.sh claim\`)" >&2
+    return $OPS_RC_NO_SLICE
+  fi
+  echo "$sid"
+  return $OPS_RC_OK
+}
+
+# _ops_post_or_queue <path> <payload> <tipo_evento> <slice_id> <etiqueta>
+# Camino común de los actos primarios: POST y, si el servidor no está, encolar el hecho.
+# Rechazo del servidor (409/422/401/403) => NUNCA se encola (no se reintenta lo rechazado).
+_ops_post_or_queue() {
+  local path="$1" payload="$2" tipo="$3" sid="$4" etiqueta="$5" resp status pfile
+  resp="$(runtime_post "$path" "$payload")"
+  status="$(runtime_http_status)"
+  case "$status" in
+    200|201|202)
+      agent_context_fetch_and_cache >/dev/null 2>&1
+      echo "$etiqueta registrado en el runtime"
+      return $OPS_RC_OK ;;
+    422)
+      echo "⛔ 422 el servidor rechazó $etiqueta: $resp" >&2
+      echo "  Compuerta mecánica funcionando: NO reintentes; corrige la causa y vuelve a medir." >&2
+      return $OPS_RC_REJECTED ;;
+    409)
+      echo "⛔ 409 el servidor rechazó $etiqueta (lease perdido o transición ya aplicada): $resp" >&2
+      echo "  Haz checkpoint local y vuelve a reclamar antes de seguir." >&2
+      return $OPS_RC_REJECTED ;;
+    401|403)
+      echo "⛔ token inválido o revocado ($status): pide un token nuevo al ADMIN." >&2
+      return $OPS_RC_REJECTED ;;
+    *)
+      pfile="$(ops_tmpjson "$payload")" || { echo "OFFLINE: no se pudo encolar $etiqueta" >&2; return $OPS_RC_OFFLINE; }
+      if ops_enqueue_from_file "$tipo" "$pfile" "$sid"; then
+        rm -f "$pfile"
+        echo "OFFLINE: $etiqueta encolado (tipo protegido, se entrega al reconectar)"
+      else
+        rm -f "$pfile"
+        echo "⚠ OFFLINE: $etiqueta NO se pudo encolar (outbox no escribible u otro fallo local) — se perderá" >&2
+      fi
+      return $OPS_RC_OFFLINE ;;
+  esac
+}
+
+# ── gate ─────────────────────────────────────────────────────────────────────────────
+# Un veredicto es un HECHO MEDIDO: acto de agente (spec §2). El nombre del gate y el
+# estado se validan en el cliente (compuerta barata, sin round-trip); la compuerta real,
+# que conoce el orden y las precondiciones, es el servidor.
+cmd_gate() {
+  local gate="${1:-}" estado="${2:-}" evfile="" ev="" mode sid evjson payload
+  if [ -z "$gate" ] || [ -z "$estado" ]; then
+    echo "uso: slice-ops.sh gate <nombre> <pass|fail|na> [--evidence «texto» | --evidence-file F]" >&2
+    return $OPS_RC_USAGE
+  fi
+  shift 2
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --evidence) ev="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --evidence-file) evfile="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  case " $OPS_SLICE_GATES " in
+    *" $gate "*) : ;;
+    *) echo "⛔ gate desconocido «${gate}». Canónicos: $OPS_SLICE_GATES" >&2; return $OPS_RC_REJECTED ;;
+  esac
+  case "$estado" in
+    pass|fail|na) : ;;
+    *) echo "⛔ estado inválido «${estado}» (pass|fail|na)" >&2; return $OPS_RC_REJECTED ;;
+  esac
+  mode="$(ops_mode)"
+  [ "$mode" = "legacy" ] && { echo "LEGACY: escribe el gate en el fichero (references/state-protocol.md)"; return $OPS_RC_LEGACY; }
+  evjson="$(_ops_evidence_json "$ev" "$evfile")"
+  payload="{\"gate\":$(ops_json_str "$gate"),\"status\":$(ops_json_str "$estado"),\"evidence\":$evjson}"
+  if [ "$mode" = "dual" ]; then
+    _ops_dual_mirror verdict_reported "$payload"
+    return $?
+  fi
+  sid="$(_ops_require_slice)" || return $OPS_RC_NO_SLICE
+  _ops_post_or_queue "$(ops_path_verdicts "$sid")" "$payload" verdict_reported "$sid" "el veredicto de «${gate}»"
+}
+
+# ── submit ───────────────────────────────────────────────────────────────────────────
+cmd_submit() {
+  local pr="" change="" mode sid payload
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --pr-url) pr="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --openspec-change) change="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  mode="$(ops_mode)"
+  [ "$mode" = "legacy" ] && { echo "LEGACY: el submit no existe en el fichero; sigue el pipeline local"; return $OPS_RC_LEGACY; }
+  payload="{\"pr_url\":$(ops_json_str "$pr"),\"openspec_change\":$(ops_json_str "$change")}"
+  if [ "$mode" = "dual" ]; then
+    _ops_dual_mirror slice_submitted "$payload"
+    return $?
+  fi
+  sid="$(_ops_require_slice)" || return $OPS_RC_NO_SLICE
+  _ops_post_or_queue "$(ops_path_submit "$sid")" "$payload" slice_submitted "$sid" "el submit del slice"
+}
+
+# ── archive ──────────────────────────────────────────────────────────────────────────
+# SIEMPRE por la cola, también con el runtime vivo: `opsx:archive` corre dentro del PR,
+# en el momento menos oportuno para una llamada síncrona, y el evento es idempotente por
+# `client_event_id`. El tipo está protegido de la cota (Task 1): un archivado no se evicta.
+cmd_archive() {
+  local pr="" change="" epic="" mode sid payload pfile
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --pr-url) pr="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --openspec-change) change="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --epic) epic="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  mode="$(ops_mode)"
+  [ "$mode" = "legacy" ] && { echo "LEGACY: archiva moviendo active_slice a history[] en el fichero"; return $OPS_RC_LEGACY; }
+  payload="{\"epic_code\":$(ops_json_str "$epic"),\"openspec_change\":$(ops_json_str "$change"),\"pr_url\":$(ops_json_str "$pr")}"
+  if [ "$mode" = "dual" ]; then
+    _ops_dual_mirror slice_archived "$payload"
+    return $?
+  fi
+  sid="$(ops_slice_id)"
+  pfile="$(ops_tmpjson "$payload")" || return $OPS_RC_OFFLINE
+  if ops_enqueue_from_file slice_archived "$pfile" "$sid"; then
+    rm -f "$pfile"
+    echo "slice_archived encolado (se entrega al reconectar; tipo protegido de la cota)"
+    return $OPS_RC_OK
+  fi
+  rm -f "$pfile"
+  echo "⚠ slice_archived NO se pudo encolar (outbox no escribible u otro fallo local)" >&2
+  return $OPS_RC_OFFLINE
+}
+
+# ── wiring ───────────────────────────────────────────────────────────────────────────
+# El checklist de cableado es el corazón del refresh de contexto: nace `failing` y solo
+# pasa a `passing` tras prueba REAL ejecutada. Se emite como eventos del agregado slice
+# (spec §4.1-C: el reducer proyecta status + kind/ref/evidence, no solo el status).
+cmd_wiring() {
+  local accion="${1:-}" mode
+  [ -n "$accion" ] && shift
+  mode="$(ops_mode)"
+  [ "$mode" = "legacy" ] && { echo "LEGACY: mantén wiring_checklist[] en el fichero"; return $OPS_RC_LEGACY; }
+  case "$accion" in
+    seed) _wiring_seed "$@" ;;
+    update) _wiring_update "$@" ;;
+    *) echo "uso: slice-ops.sh wiring seed --file items.json | wiring update <item_id> <passing|failing> [--kind K] [--ref R] [--evidence-file F]" >&2
+       return $OPS_RC_USAGE ;;
+  esac
+}
+
+# _wiring_seed --file <json array de {item_id, kind, ref}>
+_wiring_seed() {
+  local file="" sid pfile mode
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --file) file="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  [ -n "$file" ] && [ -f "$file" ] || { echo "uso: slice-ops.sh wiring seed --file items.json" >&2; return $OPS_RC_USAGE; }
+  command -v python3 >/dev/null 2>&1 || { echo "⚠ sin python3: no se puede sembrar el checklist" >&2; return $OPS_RC_OFFLINE; }
+  pfile="$(mktemp)" || return $OPS_RC_OFFLINE
+  # El payload se construye leyendo el fichero DENTRO de python3 (nunca por argv) y se
+  # normaliza: cada item nace `failing` — el estado inicial no es negociable.
+  python3 - "$file" > "$pfile" <<'PY' 2>/dev/null
+import json,sys
+try:
+    raw=json.load(open(sys.argv[1]))
+except Exception:
+    raw=[]
+if isinstance(raw,dict):
+    raw=raw.get("items") or []
+items=[]
+for it in raw if isinstance(raw,list) else []:
+    if not isinstance(it,dict):
+        continue
+    iid=it.get("item_id") or it.get("id")
+    if not iid:
+        continue
+    items.append({"item_id":iid,"kind":it.get("kind"),"ref":it.get("ref"),"status":"failing"})
+print(json.dumps({"items":items},ensure_ascii=False))
+PY
+  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
+    rm -f "$pfile"
+    return $OPS_RC_OK
+  fi
+  sid="$(ops_slice_id)"
+  if ops_enqueue_from_file wiring_checklist_seeded "$pfile" "$sid"; then
+    rm -f "$pfile"
+    echo "checklist de wiring sembrado (evento encolado)"
+    return $OPS_RC_OK
+  fi
+  rm -f "$pfile"
+  echo "⚠ checklist de wiring NO se pudo encolar (outbox no escribible u otro fallo local)" >&2
+  return $OPS_RC_OFFLINE
+}
+
+# _wiring_update <item_id> <passing|failing> [--kind K] [--ref R] [--evidence T|--evidence-file F]
+_wiring_update() {
+  local item="${1:-}" estado="${2:-}" kind="" ref="" ev="" evfile="" sid payload pfile mode
+  if [ -z "$item" ] || [ -z "$estado" ]; then
+    echo "uso: slice-ops.sh wiring update <item_id> <passing|failing> [--kind K] [--ref R] [--evidence-file F]" >&2
+    return $OPS_RC_USAGE
+  fi
+  shift 2
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --kind) kind="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --ref) ref="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --evidence) ev="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --evidence-file) evfile="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  case "$estado" in
+    passing|failing) : ;;
+    *) echo "⛔ estado inválido «${estado}» (passing|failing)" >&2; return $OPS_RC_REJECTED ;;
+  esac
+  if [ "$estado" = "passing" ] && [ -z "$ev" ] && [ -z "$evfile" ]; then
+    echo "⚠ marcando «${item}» como passing SIN evidencia: la regla dura exige prueba real ejecutada" >&2
+  fi
+  payload="{\"item_id\":$(ops_json_str "$item"),\"status\":$(ops_json_str "$estado"),\"kind\":$(ops_json_str "$kind"),\"ref\":$(ops_json_str "$ref"),\"evidence\":$(_ops_evidence_json "$ev" "$evfile")}"
+  mode="$(ops_mode)"
+  if [ "$mode" = "dual" ]; then
+    _ops_dual_mirror wiring_item_updated "$payload"
+    return $?
+  fi
+  sid="$(ops_slice_id)"
+  pfile="$(ops_tmpjson "$payload")" || return $OPS_RC_OFFLINE
+  if ops_enqueue_from_file wiring_item_updated "$pfile" "$sid"; then
+    rm -f "$pfile"
+    echo "wiring «${item}» → $estado (evento encolado)"
+    return $OPS_RC_OK
+  fi
+  rm -f "$pfile"
+  echo "⚠ wiring «${item}» NO se pudo encolar (outbox no escribible u otro fallo local)" >&2
+  return $OPS_RC_OFFLINE
+}
+
+# ── progress ─────────────────────────────────────────────────────────────────────────
+# Sustituye a progress_log[]: el event stream ES la bitácora (spec §5.6, el comparador NO
+# compara progress_log). Tipo EVICTABLE a propósito: es volumen, no hecho de dominio.
+cmd_progress() {
+  local nota="" file="" mode sid payload pfile
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --file) file="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) [ -z "$nota" ] && nota="$1"; shift ;;
+    esac
+  done
+  if [ -z "$nota" ] && [ -z "$file" ]; then
+    echo "uso: slice-ops.sh progress «nota» | --file F" >&2
+    return $OPS_RC_USAGE
+  fi
+  mode="$(ops_mode)"
+  [ "$mode" = "legacy" ] && { echo "LEGACY: apendiza la nota en progress_log[] del fichero"; return $OPS_RC_LEGACY; }
+  payload="{\"note\":$(_ops_evidence_json "$nota" "$file")}"
+  if [ "$mode" = "dual" ]; then
+    _ops_dual_mirror progress_note_recorded "$payload"
+    return $?
+  fi
+  sid="$(ops_slice_id)"
+  pfile="$(ops_tmpjson "$payload")" || return $OPS_RC_OFFLINE
+  if ops_enqueue_from_file progress_note_recorded "$pfile" "$sid"; then
+    rm -f "$pfile"
+    echo "nota de progreso encolada"
+    return $OPS_RC_OK
+  fi
+  rm -f "$pfile"
+  echo "⚠ nota de progreso NO se pudo encolar (outbox no escribible u otro fallo local)" >&2
+  return $OPS_RC_OFFLINE
+}
+
+# ── checkpoint ───────────────────────────────────────────────────────────────────────
+# El checkpoint es lo que permite que OTRO agente continúe tras una caída (protocolo §3
+# regla 2). La rama y el commit se leen del repo del PROYECTO, no del cwd de la sesión.
+cmd_checkpoint() {
+  local nota="" file="" mode sid branch commit payload root
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --note) nota="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --note-file) file="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  mode="$(ops_mode)"
+  [ "$mode" = "legacy" ] && { echo "LEGACY: registra la continuidad en session_continuity del fichero"; return $OPS_RC_LEGACY; }
+  root="$(config_root)"
+  branch="$(git -C "$root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")"
+  commit="$(git -C "$root" rev-parse HEAD 2>/dev/null || echo "")"
+  if [ "$mode" = "dual" ]; then
+    payload="{\"branch\":$(ops_json_str "$branch"),\"commit_sha\":$(ops_json_str "$commit"),\"note\":$(_ops_evidence_json "$nota" "$file")}"
+    _ops_dual_mirror checkpoint_created "$payload"
+    return $?
+  fi
+  sid="$(_ops_require_slice)" || return $OPS_RC_NO_SLICE
+  payload="{\"slice_id\":$(ops_json_str "$sid"),\"branch\":$(ops_json_str "$branch"),\"commit_sha\":$(ops_json_str "$commit"),\"note\":$(_ops_evidence_json "$nota" "$file")}"
+  _ops_post_or_queue "$OPS_PATH_CHECKPOINTS" "$payload" checkpoint_created "$sid" "el checkpoint"
+}
+
+SUB="${1:-}"
+[ $# -gt 0 ] && shift
+case "$SUB" in
+  mode) ops_mode; exit 0 ;;
+  claim) cmd_claim "$@"; exit $? ;;
+  next-step) cmd_next_step; exit $? ;;
+  gate) cmd_gate "$@"; exit $? ;;
+  submit) cmd_submit "$@"; exit $? ;;
+  archive) cmd_archive "$@"; exit $? ;;
+  wiring) cmd_wiring "$@"; exit $? ;;
+  progress) cmd_progress "$@"; exit $? ;;
+  checkpoint) cmd_checkpoint "$@"; exit $? ;;
+  fact) cmd_fact "$@"; exit $? ;;
+  propose-asset) cmd_propose_asset "$@"; exit $? ;;
+  status) cmd_status "$@"; exit $? ;;
+  escalate) cmd_escalate "$@"; exit $? ;;
+  ""|-h|--help|help) usage; exit $OPS_RC_USAGE ;;
+  *) echo "subcomando desconocido: $SUB" >&2; usage; exit $OPS_RC_USAGE ;;
+esac