@trycore/spec-build-harness 0.13.0 → 0.14.1

package/hooks/build/slice-ops.sh

@@ -4,9 +4,10 @@
 # `building-a-slice`, los comandos /build:* y los agentes, UNA invocación por transición.
 #
 #   uso: slice-ops.sh <subcomando> [opciones]
-#   subcomandos IMPLEMENTADOS (13 del plan + phase, issue #52): mode | claim | next-step |
-#                phase | gate | submit | archive | wiring | progress | checkpoint | fact |
-#                propose-asset | status | escalate.
+#   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.
 #
 # 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
@@ -38,6 +39,13 @@ uso: slice-ops.sh <subcomando> [opciones]
   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
+  propose-epic --file borrador.json            propone una épica al hub (SIN EP-XXX: la
+                                                identidad la asigna el hub al aprobar)
+  epic-status [--id P]                         estado de las propuestas (QUEUED|PROPOSED|
+                                                APPROVED|REJECTED|FAILED)
+  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)
   status [--no-refresh]                         informe local del agente
   escalate «razón» | --file F [--gate G]        registra un bloqueo (la decisión es humana)
 
@@ -97,9 +105,16 @@ PY
 # [#39] El cuerpo lleva SOLO context_hashes: `TasksNextIn` del hub no declara epic_code
 # (pydantic lo ignoraba en silencio y la cola repartía OTRA épica con claim "exitoso").
 _claim_once() {
-  local hashes body resp status reason
+  local hashes body resp status reason gv
   hashes="$(ops_context_hashes)"
-  body="{\"context_hashes\":$hashes}"
+  # [#63] La versión de grafo viaja SOLO si la conocemos: un hub que no versiona (instancia
+  # antigua) debe seguir viendo el mismo cuerpo de siempre — compatibilidad hacia atrás.
+  gv="$(_runtime_graph_version)"
+  if [ -n "$gv" ]; then
+    body="{\"context_hashes\":$hashes,\"graph_version\":$gv}"
+  else
+    body="{\"context_hashes\":$hashes}"
+  fi
   resp="$(runtime_post "$OPS_PATH_CLAIM" "$body")"
   status="$(runtime_http_status)"
   case "$status" in
@@ -115,6 +130,15 @@ _claim_once() {
       reason="$(_claim_field "$resp" reason)"
       [ -n "$reason" ] || reason="$(_claim_field "$resp" error)"
       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
           return 20 ;;
@@ -185,24 +209,36 @@ cmd_claim() {
   bash "$HERE/context-sync.sh" "$expected" >/dev/null 2>&1
   _claim_once
   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.
+  if [ $rc -eq 20 ] || [ $rc -eq 21 ]; then
+    # Drift, contención o grafo rancio: refrescar el estado REAL y reintentar EXACTAMENTE una
+    # vez (protocolo §7). Pasar "" a context-sync.sh no fuerza nada — su fallback recae en la
+    # caché de credenciales, que en el escenario de drift YA coincide con el lock local —, así
+    # que se refresca antes con GET /agent/context y se usa SU manifest_hash como EXPECTED.
+    # Para `stale_graph` ese mismo refresco es justamente lo que trae la versión nueva.
     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
+    local prev_rc=$rc
     _claim_once
     rc=$?
+    if [ $rc -eq 21 ]; then
+      # Segundo 409 con el grafo ya refrescado: no es una carrera, es un desfase que el
+      # cliente no puede resolver solo. El mensaje NOMBRA el desfase y la acción.
+      local gs
+      gs="$(runtime_graph_status_read)"
+      echo "⛔ el hub rechaza el claim por versión de grafo obsoleta, incluso tras refrescar." >&2
+      echo "  desfase: $gs" >&2
+      echo "  El backlog del hub cambió mientras reclamabas (una épica propuesta, aprobada o" >&2
+      echo "  rechazada). Vuelve a intentarlo en unos segundos; si persiste, revisa en la consola" >&2
+      echo "  del hub que este proyecto no esté a mitad de un import de grafo." >&2
+      return $OPS_RC_REJECTED
+    fi
     if [ $rc -eq 20 ]; then
       echo "otro agente tomó la tarea; pide la siguiente"
       return $OPS_RC_NO_WORK
     fi
+    # Un claim correcto tras un stale_graph deja el marcador de desfase sin sentido.
+    [ $rc -eq 0 ] && [ "$prev_rc" -eq 21 ] && runtime_graph_clear_stale
   fi
   return $rc
 }
@@ -426,6 +462,415 @@ cmd_propose_asset() {
   esac
 }
 
+# ── propose-epic ─────────────────────────────────────────────────────────────────────
+# [#62] La terminal PROPONE, el hub decide la identidad, un humano aprueba. El agente pierde
+# a propósito la potestad de inventar el `EP-XXX`: elegirlo mirando `epicas.md` es lo que hizo
+# que dos terminales crearan EP-042 y EP-043 el mismo día y sus historias colisionaran.
+# Va por el carril directo de la outbox (endpoint propio, hub#113) para sobrevivir a estar
+# offline, y se intenta despachar en el acto para poder devolver el identificador del hub.
+
+# _epic_draft_normalize <fichero> — imprime el cuerpo de la propuesta ya normalizado, o "" con
+# rc 2 si el borrador no vale. `epic_code`/`code`/`id` se DESCARTAN (no se rechaza la
+# propuesta: la decisión de hub#113 es ignorar el campo, no fallar por él).
+_epic_draft_normalize() {
+  local f="$1"
+  # [Importante 4] sin python3 no es "borrador inválido" (rc 2 de uso): es una degradación de
+  # infraestructura — se anuncia con esas palabras y con OFFLINE, para que no se confunda con
+  # un borrador mal escrito.
+  command -v python3 >/dev/null 2>&1 || {
+    echo "⛔ sin python3: no se puede validar el borrador en local" >&2
+    return $OPS_RC_OFFLINE
+  }
+  # OJO: sin `2>/dev/null` aquí — el llamador captura este stderr en `$errf` para mostrar
+  # 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"}
+try:
+    d=json.load(open(sys.argv[1]))
+except Exception:
+    print("⛔ el borrador no es un JSON legible", file=sys.stderr); raise SystemExit(2)
+if not isinstance(d,dict):
+    print("⛔ el borrador debe ser un objeto JSON", file=sys.stderr); raise SystemExit(2)
+title=(d.get("title") or "").strip()
+objective=(d.get("objective") or "").strip()
+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"
+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})
+    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]
+        stories.append(st)
+out={"title":title[:300],"objective":objective[:2000],"layer":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"}
+if ignorados:
+    print("IGNORADOS %s" % ",".join(ignorados), file=sys.stderr)
+print(json.dumps(out,ensure_ascii=False))
+PY
+}
+
+cmd_propose_epic() {
+  local file="" mode pid norm errf rc cid pfile ack proposal_id reason
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --file) file="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  if [ -z "$file" ]; then
+    echo "uso: slice-ops.sh propose-epic --file borrador.json" >&2
+    echo "  borrador: {title, objective, layer, files_scope[], depends_on[], stories[]}" >&2
+    echo "  SIN EP-XXX: el código lo asigna el hub al aprobar." >&2
+    return $OPS_RC_USAGE
+  fi
+  [ -f "$file" ] || { echo "⛔ no existe el borrador: $file" >&2; return $OPS_RC_USAGE; }
+  mode="$(ops_mode)"
+  # [Ronda final] El texto ramifica por modo: en `dual` SÍ hay hub (el fichero es primario,
+  # pero el proyecto está registrado), y decirle al usuario «no hay hub al que proponer» le
+  # hacía buscar un problema de conexión que no existe.
+  if [ "$mode" = "dual" ]; then
+    echo "DUAL: el fichero local es primario y el carril de propuesta solo opera en modo \`runtime\`."
+    echo "La épica se crea en discovery (\`/trycore:epicas\`) o, si es la caparazón, por el"
+    echo "carve-out de /build:onboard Fase 2c; llega al hub por el import de admin."
+    return $OPS_RC_LEGACY
+  fi
+  if [ "$mode" != "runtime" ]; then
+    echo "LEGACY: la épica se crea en discovery (\`/trycore:epicas\`) o, si es la caparazón,"
+    echo "por el carve-out de /build:onboard Fase 2c. No hay hub al que proponer."
+    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; }
+
+  errf="$(mktemp)" || return $OPS_RC_OFFLINE
+  norm="$(_epic_draft_normalize "$file" 2>"$errf")"
+  rc=$?
+  # [Importante 4] rc OFFLINE (sin python3) no es lo mismo que rc USAGE (borrador inválido):
+  # el primero es fallo de infraestructura, reintentable; el segundo es del agente.
+  if [ "$rc" -eq "$OPS_RC_OFFLINE" ]; then
+    cat "$errf" >&2
+    rm -f "$errf"
+    return $OPS_RC_OFFLINE
+  fi
+  if [ $rc -ne 0 ] || [ -z "$norm" ]; then
+    cat "$errf" >&2
+    rm -f "$errf"
+    return $OPS_RC_USAGE
+  fi
+  if grep -q '^IGNORADOS ' "$errf"; then
+    echo "⚠ código de épica ignorado ($(sed -n 's/^IGNORADOS //p' "$errf")): la identidad la asigna el hub al aprobar." >&2
+  fi
+  rm -f "$errf"
+
+  pfile="$(ops_tmpjson "$norm")" || return $OPS_RC_OFFLINE
+  # El `1` final pide el estampado de la versión de grafo AL DESPACHAR [#63]: una propuesta
+  # encolada offline debe salir con la versión vigente en ese momento, no con la de ayer.
+  cid="$(runtime_enqueue_direct epic_proposed POST "$(ops_path_epic_proposals "$pid")" "$pfile" 1)"
+  rm -f "$pfile"
+  if [ -z "$cid" ]; then
+    echo "⛔ no se pudo encolar la propuesta (outbox no escribible): guárdala y reintenta." >&2
+    return $OPS_RC_OFFLINE
+  fi
+  ops_epic_ledger_upsert "{\"client_event_id\":\"$cid\",\"status\":\"QUEUED\",\"proposal_id\":null,\"epic_code\":null,\"written_back_at\":null,\"draft\":$norm}"
+
+  # Intento de despacho inmediato: si hay red, la skill puede enseñar YA el identificador.
+  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)"
+    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."
+    echo "El código EP-XXX lo asigna el hub AL APROBAR. Consulta con \`slice-ops.sh epic-status\`."
+    return $OPS_RC_OK
+  fi
+  reason="$(ops_epic_rejected_reason "$cid")"
+  if [ -n "$reason" ]; then
+    ops_epic_ledger_upsert "{\"client_event_id\":\"$cid\",\"status\":\"FAILED\",\"reason\":$(ops_json_str "$reason")}"
+    echo "⛔ la propuesta no se pudo entregar: $reason" >&2
+    return $OPS_RC_REJECTED
+  fi
+  echo "propuesta encolada: $cid"
+  # [Ronda final] El texto ya no afirma «sin conexión»: desde que el despacho lleva mutex
+  # (A1), este camino también se toma cuando el daemon estaba despachando la cola en ese
+  # mismo instante y el intento en primer plano cedió el turno. La propuesta está encolada y
+  # el daemon la lleva en los dos casos —el rc 5 y la conducta no cambian—, pero nombrar una
+  # causa que puede ser falsa manda al usuario a revisar una red que funciona.
+  echo "PENDIENTE: se despachará sola (el daemon de heartbeat la lleva). Sin conexión aún, o"
+  echo "el daemon estaba drenando la cola en este instante. \`slice-ops.sh epic-status\` la sigue."
+  echo "NO escribas la épica en docs/03-backlog/epicas.md: el código lo asigna el hub al aprobar."
+  return $OPS_RC_OFFLINE
+}
+
+# ── epic-status ──────────────────────────────────────────────────────────────────────
+# [#62] Resuelve el ciclo de vida de cada propuesta del ledger. Dos fuentes por estado:
+#   QUEUED   → mira el ack del carril directo (¿ya se despachó?) o el rechazo local.
+#   PROPOSED → pregunta al hub por su estado (APPROVED con `epic_code`, o REJECTED con razón).
+# Es INFORMATIVO: rc 0 siempre en runtime, pase lo que pase.
+cmd_epic_status() {
+  local only="" mode pid entries n i cid pidv st ack resp status tmp
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --id) only="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  mode="$(ops_mode)"
+  if [ "$mode" = "dual" ]; then
+    echo "DUAL: no hay propuestas que consultar (el carril solo opera en modo \`runtime\`);"
+    echo "las épicas viven en docs/03-backlog/epicas.md"
+    return $OPS_RC_LEGACY
+  fi
+  if [ "$mode" != "runtime" ]; then
+    echo "LEGACY: no hay propuestas que consultar; las épicas viven en docs/03-backlog/epicas.md"
+    return $OPS_RC_LEGACY
+  fi
+  command -v python3 >/dev/null 2>&1 || { echo "sin python3: no se puede leer el ledger"; return $OPS_RC_OK; }
+  pid="$(runtime_field project_id)"
+
+  # Primero, la parte que NO toca la red: acks y rechazos del carril directo.
+  tmp="$(mktemp)" || return $OPS_RC_OK
+  ops_epic_ledger_read > "$tmp"
+  n="$(python3 -c 'import json,sys; print(len(json.load(open(sys.argv[1]))["proposals"]))' "$tmp" 2>/dev/null)"
+  case "$n" in ''|*[!0-9]*) n=0 ;; esac
+  if [ "$n" -eq 0 ]; then
+    rm -f "$tmp"
+    echo "sin propuestas de épica registradas en esta copia del proyecto"
+    return $OPS_RC_OK
+  fi
+  i=0
+  while [ "$i" -lt "$n" ]; do
+    cid="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["proposals"][int(sys.argv[2])].get("client_event_id") or "")' "$tmp" "$i" 2>/dev/null)"
+    pidv="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["proposals"][int(sys.argv[2])].get("proposal_id") or "")' "$tmp" "$i" 2>/dev/null)"
+    st="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["proposals"][int(sys.argv[2])].get("status") or "")' "$tmp" "$i" 2>/dev/null)"
+    i=$((i + 1))
+    [ -n "$only" ] && [ "$only" != "$pidv" ] && continue
+
+    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)"
+        st=PROPOSED
+        ops_epic_ledger_upsert "{\"client_event_id\":\"$cid\",\"status\":\"PROPOSED\",\"proposal_id\":$(ops_json_str "$pidv")}"
+      else
+        local rej; rej="$(ops_epic_rejected_reason "$cid")"
+        if [ -n "$rej" ]; then
+          ops_epic_ledger_upsert "{\"client_event_id\":\"$cid\",\"status\":\"FAILED\",\"reason\":$(ops_json_str "$rej")}"
+          echo "$cid  FAILED       $rej"
+          continue
+        fi
+        echo "$cid  QUEUED       aún en la cola: se despachará al recuperar conexión"
+        continue
+      fi
+    fi
+
+    if [ "$st" = "PROPOSED" ] && [ -n "$pidv" ] && [ -n "$pid" ]; then
+      resp="$(runtime_get "$(ops_path_epic_proposal "$pid" "$(ops_urlenc "$pidv")")")"
+      status="$(runtime_http_status)"
+      case "$status" in
+        200)
+          st="$(_claim_field "$resp" 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)"
+              [ -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)"
+              ops_epic_ledger_upsert "{\"client_event_id\":\"$cid\",\"status\":\"REJECTED\",\"reason\":$(ops_json_str "$why")}"
+              echo "$pidv  REJECTED     ${why:-sin motivo registrado}" ;;
+            *)
+              echo "$pidv  PROPOSED     pendiente de aprobación humana en la consola del hub" ;;
+          esac ;;
+        404)
+          echo "$pidv  ?            el hub no expone la consulta de propuestas: instancia sin soporte (hub#113 pendiente)" ;;
+        401|403)
+          echo "$pidv  ?            token inválido o sin permiso ($status): habla con el ADMIN" ;;
+        *)
+          echo "$pidv  ?            OFFLINE: no se pudo consultar (status $status); se conserva el estado local" ;;
+      esac
+      continue
+    fi
+    echo "${pidv:-$cid}  $st"
+  done
+  rm -f "$tmp"
+  return $OPS_RC_OK
+}
+
+# ── epic-writeback ───────────────────────────────────────────────────────────────────
+# [#62] La vuelta del ciclo: aprobada la propuesta (hub#114), la épica se escribe en
+# docs/03-backlog/epicas.md con el código que asignó el HUB. El fichero queda como
+# PROYECCIÓN del grafo, nunca al revés — por eso el bloque es mecánico y siempre el mismo:
+# una redacción libre por write-back haría que el fichero y el hub se separaran a cada pasada.
+# Idempotente: si el `EP-XXX` ya tiene sección en el fichero, no se duplica (se marca hecho).
+# Los códigos de HU los pone el hub si los trae; el arnés NUNCA los inventa (inventarlos es
+# exactamente la colisión que motivó el issue).
+# _epic_writeback_path_ok <ruta> <directorio-permitido> — imprime "OK" solo si la ruta cae
+# DENTRO del directorio permitido, con symlinks y `..` ya resueltos (`realpath` sobre ambos).
+# Sin python3 no se puede resolver la ruta: imprime "" (rechaza). Preferir el rechazo al
+# permiso es lo correcto aquí — es una compuerta de escritura sobre ficheros ajenos.
+_epic_writeback_path_ok() {
+  command -v python3 >/dev/null 2>&1 || { echo ""; return; }
+  python3 - "$1" "$2" <<'PY' 2>/dev/null
+import os,sys
+try:
+    t=os.path.realpath(sys.argv[1])
+    base=os.path.realpath(sys.argv[2])
+except Exception:
+    print(""); raise SystemExit(0)
+print("OK" if t.startswith(base + os.sep) else "")
+PY
+}
+
+cmd_epic_writeback() {
+  local only="" target="" mode root wrote rc
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --id) only="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      --file) target="${2:-}"; [ $# -ge 2 ] && shift 2 || shift ;;
+      *) shift ;;
+    esac
+  done
+  mode="$(ops_mode)"
+  if [ "$mode" = "dual" ]; then
+    echo "DUAL: el fichero local es primario; docs/03-backlog/epicas.md ya es la fuente y no"
+    echo "hay grafo del hub que proyectar sobre él (el carril solo opera en modo \`runtime\`)"
+    return $OPS_RC_LEGACY
+  fi
+  if [ "$mode" != "runtime" ]; then
+    echo "LEGACY: la épica ya vive en docs/03-backlog/epicas.md; no hay grafo que proyectar"
+    return $OPS_RC_LEGACY
+  fi
+  command -v python3 >/dev/null 2>&1 || { echo "⛔ sin python3 no se puede escribir el fichero" >&2; return $OPS_RC_OFFLINE; }
+  root="$(config_root)"
+  [ -n "$target" ] || target="$root/docs/03-backlog/epicas.md"
+  # [Ronda final · METODOLOGIA §9.2] `--file` aceptaba CUALQUIER ruta: con eso, un carve-out
+  # de escritura acotado a cuatro sitios se convertía en una escritura libre sobre `docs/`, y
+  # los Guardrails de /build:epic prometen justo lo contrario. La ruta se restringe al subárbol
+  # del backlog (con symlinks y `..` resueltos), y la comprobación va ANTES de la existencia:
+  # una ruta fuera del carve-out se rechaza exista o no.
+  if [ "$(_epic_writeback_path_ok "$target" "$root/docs/03-backlog")" != "OK" ]; then
+    echo "⛔ --file fuera del carve-out: $target" >&2
+    echo "  El write-back solo escribe dentro de $root/docs/03-backlog/ (METODOLOGIA §9.2)." >&2
+    echo "  Usa esa ruta (o ninguna: por defecto es docs/03-backlog/epicas.md)." >&2
+    return $OPS_RC_USAGE
+  fi
+  if [ ! -f "$target" ]; then
+    echo "⛔ no existe $target — el backlog de discovery es su dueño: créalo allí primero." >&2
+    return $OPS_RC_NO_SLICE
+  fi
+  # [Importante 1/2/3] fsync en AMBAS escrituras (epicas.md es un fichero de discovery que
+  # el arnés solo toca por carve-out: dejarlo truncado por un corte de energía es exactamente
+  # el daño que la restricción prohíbe); epicas.md solo se reescribe si de verdad hay algo que
+  # escribir (si no, cada invocación en vacío convertiría CRLF→LF y degradaría los permisos de
+  # 0644 a 0600 heredados del `mkstemp` de un fichero AJENO); y si el ledger no se puede
+  # persistir, la excepción SUBE (no se traga): reportar éxito con el ledger desincronizado
+  # es peor que fallar ruidosamente.
+  wrote="$(python3 - "$(ops_epic_ledger_path)" "$target" "$only" <<'PY' 2>/dev/null
+import json,sys,os,tempfile,datetime,re
+ledger,target,only=sys.argv[1],sys.argv[2],sys.argv[3]
+try:
+    d=json.load(open(ledger))
+except Exception:
+    d={}
+ps=[p for p in (d.get("proposals") or []) if isinstance(p,dict)]
+texto=open(target,encoding="utf-8").read()
+escritas=[]
+for p in ps:
+    if p.get("status")!="APPROVED" or p.get("written_back_at"):
+        continue
+    if only and p.get("proposal_id")!=only:
+        continue
+    code=p.get("epic_code")
+    if not code:
+        continue
+    epic=p.get("epic") or p.get("draft") or {}
+    # [Ronda final] La sangría permitida se alinea con RE_ENCABEZADO de graph-bundle.py
+    # (`^\s{0,3}#{1,6}`): con `#` exigido en columna 0, un encabezado sangrado —que el
+    # extractor SÍ reconoce— daba falso negativo y el write-back DUPLICABA la sección.
+    if re.search(r"^[ \t]{0,3}#{1,6}\s+.*\b%s\b" % re.escape(code), texto, re.M):
+        p["written_back_at"]=datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        continue
+    deps=[str(x) for x in (epic.get("depends_on") or [])]
+    lineas=["", "## %s — %s" % (code, epic.get("title") or "sin título"), "",
+            "- layer: %s" % (epic.get("layer") or "business"),
+            "- origin: harness-writeback",
+            "- depende_de: [%s]" % ", ".join(deps),
+            "- propuesta: %s (aprobada en el hub)" % (p.get("proposal_id") or "?"),
+            "", "**Objetivo**: %s" % (epic.get("objective") or ""), ""]
+    historias=epic.get("stories") or []
+    if historias:
+        lineas.append("**Historias**")
+        for h in historias:
+            if not isinstance(h,dict):
+                continue
+            t=h.get("title") or ""
+            c=h.get("code")
+            lineas.append("- %s — %s" % (c,t) if c else "- %s" % t)
+        lineas.append("")
+    texto=texto.rstrip("\n")+"\n"+"\n".join(lineas)
+    p["written_back_at"]=datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    escritas.append(code)
+if escritas:
+    dirn=os.path.dirname(target) or "."
+    fd,tmp=tempfile.mkstemp(dir=dirn,prefix=".epicas.",suffix=".tmp")
+    try:
+        with os.fdopen(fd,"w",encoding="utf-8") as out:
+            out.write(texto)
+            out.flush(); os.fsync(out.fileno())
+        os.replace(tmp,target)
+    except Exception:
+        try: os.unlink(tmp)
+        except OSError: pass
+        raise
+ldir=os.path.dirname(ledger) or "."
+fd,tmp=tempfile.mkstemp(dir=ldir,prefix=".epic-proposals.",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())
+    os.replace(tmp,ledger)
+except Exception:
+    try: os.unlink(tmp)
+    except OSError: pass
+    raise
+print(" ".join(escritas))
+PY
+)"
+  rc=$?
+  # [Importante 3/4] rc != 0 del heredoc es un fallo de E/S (epicas.md o el ledger no se
+  # pudieron escribir), NUNCA "no había trabajo" — un `$wrote` vacío por éxito (rc 0, nada
+  # pendiente) y un `$wrote` vacío por excepción (rc != 0) son cosas distintas.
+  if [ "$rc" -ne 0 ]; then
+    echo "⛔ el write-back no se pudo completar (fallo de E/S al escribir $target o el ledger): reintenta." >&2
+    return $OPS_RC_OFFLINE
+  fi
+  if [ -z "$wrote" ]; then
+    echo "nada que escribir: no hay propuestas APPROVED pendientes (consulta \`slice-ops.sh epic-status\`)"
+    return $OPS_RC_NO_WORK
+  fi
+  echo "escritas en $target: $wrote"
+  echo "El fichero es una PROYECCIÓN del grafo del hub: no edites el código a mano."
+  echo "Las HU sin código las numera discovery (\`/trycore:*\`): el arnés no las inventa."
+  return $OPS_RC_OK
+}
+
 # ── 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
@@ -465,10 +910,44 @@ cmd_status() {
   else
     echo "contexto:     $lock  ✓ v$(projection_get context.version "?") (${age}s)"
   fi
+  # [#63] La versión de grafo es la foto del BACKLOG. Solo se menciona si el hub versiona:
+  # inventarla en una instancia antigua sería ruido sin significado.
+  local gv gs gserver
+  gv="$(projection_get context.graph_version "")"
+  if [ -n "$gv" ]; then
+    gs="$(runtime_graph_status_read)"
+    gserver="$(printf '%s' "$gs" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("server") or "")' 2>/dev/null)"
+    # [Ronda de arreglo 1, Important 3] La comparación es «servidor MAYOR que local», no
+    # «distinto»: un marcador de desfase que se quedó pegado con un `server` viejo (porque el
+    # carril directo no lo limpiaba al despachar con éxito — ya corregido) podía apuntar a una
+    # versión POR DEBAJO de la local, y `!=` mentía diciendo «por detrás» con el local por
+    # delante. `2>/dev/null` deja la comparación fail-open si algún valor no es entero.
+    if [ -n "$gserver" ] && [ "$gserver" -gt "$gv" ] 2>/dev/null; then
+      echo "grafo:        v$gv  ⚠ por detrás del hub (v$gserver): refresca antes de reclamar o proponer"
+    else
+      echo "grafo:        v$gv"
+    fi
+  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 \
+  local hbf hbstatus
+  hbf="$(config_root)/.claude/state/heartbeat-status.json"
+  if [ -f "$hbf" ]; then
+    grep -q '"lease_lost": *true' "$hbf" 2>/dev/null \
       && echo "              ⚠ lease perdido: haz checkpoint y vuelve a reclamar"
+    # [#61] Una caché vieja porque la red está caída NO es lo mismo que una caché vieja
+    # porque nadie la pidió: la primera exige no cerrar gates a ciegas.
+    if grep -q '"context_stale": *true' "$hbf" 2>/dev/null; then
+      hbstatus="$(command -v python3 >/dev/null 2>&1 && python3 - "$hbf" <<'PY' 2>/dev/null
+import json,sys
+try:
+    print(json.load(open(sys.argv[1])).get("last_context_status"))
+except Exception:
+    print("?")
+PY
+)"
+      echo "              ⚠ el heartbeat no pudo refrescar /agent/context (último intento: ${hbstatus:-?})"
+      echo "                se opera con la última proyección buena; no cierres gates a ciegas"
+    fi
   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"
@@ -1075,6 +1554,9 @@ case "$SUB" in
   checkpoint) cmd_checkpoint "$@"; exit $? ;;
   fact) cmd_fact "$@"; exit $? ;;
   propose-asset) cmd_propose_asset "$@"; exit $? ;;
+  propose-epic) cmd_propose_epic "$@"; exit $? ;;
+  epic-status) cmd_epic_status "$@"; exit $? ;;
+  epic-writeback) cmd_epic_writeback "$@"; exit $? ;;
   status) cmd_status "$@"; exit $? ;;
   escalate) cmd_escalate "$@"; exit $? ;;
   ""|-h|--help|help) usage; exit $OPS_RC_USAGE ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trycore/spec-build-harness",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Arnés agéntico de construcción de Trycore para Claude Code: pipeline de dos loops (slice por épica + release gate) con gates de calidad, estado compartido y OpenSpec. Compañero de @trycore/spec-product-flow. Agnóstico al proyecto.",
   "type": "module",
   "bin": {

package/scripts/tests/test-config.sh

@@ -22,4 +22,45 @@ got="$(BUILD_CONFIG_FILE="$TMP/cfg.json" config_get runtime.mode legacy)"
 got="$(bash -c 'source "$1/hooks/build/lib/state-io.sh" 2>/dev/null && BUILD_CONFIG_FILE="$2" config_get context.warning_pct 35' _ "$ROOT" "$TMP/cfg.json" 2>&1)"
 [ "$got" = 40 ] && echo "OK state-io re-exporta config_get" || { echo "FAIL state-io no re-exporta ($got)"; fail=1; }
 
+# ── config_root en worktrees ──────────────────────────────────────────────────
+# El estado del arnés está en .gitignore (secretos + working state), así que NO
+# viaja a un `git worktree add`. Resolviendo la raíz solo por --show-toplevel, el
+# agente que arranca en un worktree se queda sin credenciales y opera huérfano:
+# sin identidad, sin lease y con los guards inhibidos. Nadie lo probaba, y por eso
+# sobrevivió hasta 0.13.0.
+# `git rev-parse --git-common-dir` devuelve la ruta ya resuelta, y en macOS /var es
+# un symlink a /private/var: se compara contra la ruta FÍSICA (pwd -P) para no
+# medir la forma en que se escribió el path.
+MAIN="$(mkdir -p "$TMP/main" && cd "$TMP/main" && pwd -P)"
+mkdir -p "$MAIN/.claude/state"
+git -C "$MAIN" init -q 2>/dev/null
+git -C "$MAIN" config user.email t@t.io; git -C "$MAIN" config user.name t
+echo x > "$MAIN/f"; git -C "$MAIN" add -A >/dev/null 2>&1; git -C "$MAIN" commit -qm init >/dev/null 2>&1
+echo '{"runtime_url":"http://localhost"}' > "$MAIN/.claude/state/runtime.credentials"
+WT="$TMP/wt"   # lo crea `git worktree add`, se normaliza al usarlo
+git -C "$MAIN" worktree add -q "$WT" -b wt-test >/dev/null 2>&1
+
+got="$(cd "$WT" && unset CLAUDE_PROJECT_DIR; config_root)"
+[ "$got" = "$MAIN" ] && echo "OK config_root cae al clon principal desde un worktree" \
+  || { echo "FAIL config_root en worktree ($got, esperado $MAIN)"; fail=1; }
+
+# Con CLAUDE_PROJECT_DIR apuntando al worktree (que es lo que hace el harness de
+# Claude Code al abrir una sesión ahí) el resultado debe ser el mismo: la variable
+# dice dónde trabaja el agente, no dónde vive el estado del arnés.
+got="$(cd "$WT" && CLAUDE_PROJECT_DIR="$WT" config_root)"
+[ "$got" = "$MAIN" ] && echo "OK config_root ignora CLAUDE_PROJECT_DIR sin estado" \
+  || { echo "FAIL config_root con CLAUDE_PROJECT_DIR ($got, esperado $MAIN)"; fail=1; }
+
+# Idempotencia: en un clon normal con estado propio, nada cambia.
+got="$(cd "$MAIN" && CLAUDE_PROJECT_DIR="$MAIN" config_root)"
+[ "$got" = "$MAIN" ] && echo "OK config_root respeta el clon con estado propio" \
+  || { echo "FAIL config_root en clon normal ($got)"; fail=1; }
+
+# Y sin estado en ninguna parte (proyecto que aún no usa el arnés) se devuelve el
+# candidato tal cual: no se inventa una raíz ajena.
+BARE="$TMP/bare"; mkdir -p "$BARE"
+got="$(cd "$BARE" && CLAUDE_PROJECT_DIR="$BARE" config_root)"
+[ "$got" = "$BARE" ] && echo "OK config_root sin estado devuelve el candidato" \
+  || { echo "FAIL config_root sin estado ($got)"; fail=1; }
+
 exit $fail