@trycore/spec-build-harness 0.12.0 → 0.14.0

package/scripts/tests/test-skill-ops.sh

@@ -30,6 +30,29 @@ source "$ROOT/hooks/build/lib/runtime-ops.sh" 2>/dev/null || { echo "FAIL no exi
 [ "$(ops_path_mirror p-1)" = "/projects/p-1/mirror/transitions" ] && echo "OK ops_path_mirror" || { echo "FAIL ops_path_mirror"; fail=1; }
 [ "$(ops_path_front_integration f-1 ak-1)" = "/fronts/f-1/members/ak-1/integration" ] && echo "OK ops_path_front_integration" || { echo "FAIL ops_path_front_integration"; fail=1; }
 
+# [#62] Tabla de rutas de la propuesta de épica: un solo sitio donde se escriben rutas.
+[ "$(ops_path_epic_proposals p-1)" = "/projects/p-1/epic-proposals" ] \
+  && echo "OK ops_path_epic_proposals" || { echo "FAIL ops_path_epic_proposals"; fail=1; }
+[ "$(ops_path_epic_proposal p-1 prop-7)" = "/projects/p-1/epic-proposals/prop-7" ] \
+  && echo "OK ops_path_epic_proposal" || { echo "FAIL ops_path_epic_proposal"; fail=1; }
+
+# [#62] Ledger: upsert por client_event_id, sin duplicar, conservando lo no mencionado.
+rm -f "$(ops_epic_ledger_path)"
+ops_epic_ledger_upsert '{"client_event_id":"cid-1","status":"QUEUED","draft":{"title":"Notificaciones"}}'
+ops_epic_ledger_upsert '{"client_event_id":"cid-1","status":"PROPOSED","proposal_id":"prop-7"}'
+ops_epic_ledger_upsert '{"client_event_id":"cid-2","status":"QUEUED"}'
+ops_epic_ledger_read | python3 -c "
+import json,sys
+d=json.load(sys.stdin); ps=d['proposals']
+e=[p for p in ps if p['client_event_id']=='cid-1'][0]
+ok = len(ps)==2 and e['status']=='PROPOSED' and e['proposal_id']=='prop-7' \
+     and e['draft']['title']=='Notificaciones'
+print('SI' if ok else 'NO')" | grep -q SI \
+  && echo "OK el ledger hace upsert sin duplicar ni perder el borrador" \
+  || { echo "FAIL upsert del ledger"; fail=1; }
+[ "$(PATH=/var/empty ops_epic_ledger_read)" = '{"proposals":[]}' ] \
+  && echo "OK el ledger sin python3 devuelve vacio" || { echo "FAIL ledger sin python3"; fail=1; }
+
 # --- ops_json_str: comillas, saltos de línea y tildes por STDIN (nunca por argv) ---
 got="$(ops_json_str 'una "cita" con ñ y
 salto')"
@@ -416,6 +439,53 @@ echo "$out" | grep -q "slice_archived" && echo "$out" | grep -q "archivar exige
   && echo "OK status muestra tipo y razón del rechazo más reciente" || { echo "FAIL status sin razón del último rechazo: $out"; fail=1; }
 rm -rf "$PROJ/.claude/state/outbox/rejected"
 
+# [#63] status muestra la versión de grafo y avisa si va por detrás.
+runtime_projection_write '{"fetched_at":"2099-01-01T00:00:00Z","active_slice":null,"nudges":[],"context":{"manifest_hash":"sha256:v2","version":9,"graph_version":42}}'
+runtime_graph_clear_stale
+out="$(bash "$SO" status --no-refresh 2>&1)"
+echo "$out" | grep -q 'grafo: *v42' && echo "OK status muestra la version de grafo" \
+  || { echo "FAIL status sin version de grafo"; fail=1; }
+echo "$out" | grep -qi 'por detrás' && { echo "FAIL status avisa de desfase inexistente"; fail=1; } \
+  || echo "OK status calla sin desfase"
+runtime_graph_note_stale 42 45
+out="$(bash "$SO" status --no-refresh 2>&1)"
+echo "$out" | grep -qi 'por detrás' && echo "$out" | grep -q '45' \
+  && echo "OK status avisa del desfase de grafo" || { echo "FAIL status sin aviso de desfase"; fail=1; }
+# [Ronda de arreglo 1, Important 3] Un marcador de desfase VIEJO (el carril directo no lo
+# limpiaba al despachar con éxito) puede quedar apuntando a una versión POR DEBAJO de la
+# local, si la proyección avanzó después. `!=` mentiría diciendo "por detrás" con el local
+# por delante; la comparación correcta es "servidor > local".
+runtime_projection_write '{"fetched_at":"2099-01-01T00:00:00Z","active_slice":null,"nudges":[],"context":{"manifest_hash":"sha256:v2","version":9,"graph_version":50}}'
+out="$(bash "$SO" status --no-refresh 2>&1)"
+echo "$out" | grep -q 'grafo: *v50' && ! echo "$out" | grep -qi 'por detrás' \
+  && echo "OK un marcador de desfase con server < local no miente diciendo «por detrás»" \
+  || { echo "FAIL status avisa de desfase con el local por delante: $out"; fail=1; }
+runtime_graph_clear_stale
+# Hub que no versiona: ni línea de grafo ni ruido.
+runtime_graph_clear_stale
+runtime_projection_write '{"fetched_at":"2099-01-01T00:00:00Z","active_slice":null,"nudges":[],"context":{"manifest_hash":"sha256:v2","version":9}}'
+out="$(bash "$SO" status --no-refresh 2>&1)"
+echo "$out" | grep -q 'grafo:' && { echo "FAIL status inventa version de grafo"; fail=1; } \
+  || echo "OK sin hub que versione, status no menciona el grafo"
+
+# [#61] status distingue «cache vieja» de «el heartbeat no pudo refrescarla».
+python3 -c "
+import json
+json.dump({'lease_lost': False, 'context_stale': True, 'last_context_status': '000'},
+          open('$PROJ/.claude/state/heartbeat-status.json','w'), indent=2)"
+out="$(bash "$ROOT/hooks/build/slice-ops.sh" status --no-refresh 2>&1)"
+echo "$out" | grep -q 'no pudo refrescar /agent/context' \
+  && echo "OK status avisa del refresco fallido del heartbeat" \
+  || { echo "FAIL status no avisa del refresco fallido"; fail=1; }
+python3 -c "
+import json
+json.dump({'lease_lost': False, 'context_stale': False, 'last_context_status': 200},
+          open('$PROJ/.claude/state/heartbeat-status.json','w'), indent=2)"
+out="$(bash "$ROOT/hooks/build/slice-ops.sh" status --no-refresh 2>&1)"
+echo "$out" | grep -q 'no pudo refrescar /agent/context' \
+  && { echo "FAIL status avisa de un refresco sano"; fail=1; } \
+  || echo "OK status calla con el refresco sano"
+
 # status es informativo: NUNCA falla aunque no haya nada.
 rm -f "$PROJ/.claude/state/runtime-projection.json"
 rc=0; out="$(TRYCORE_RUNTIME_MODE=legacy bash "$SO" status --no-refresh)" || rc=$?
@@ -1545,6 +1615,324 @@ PYX
 rm -f "$PROJ/.claude/state/outbox/"*.json "$PROJ/.claude/state/outbox/.dispatch-state.json"
 runtime_credentials_merge "{\"runtime_url\":\"http://127.0.0.1:$PORT_GA\"}"
 
+# ══════════════ slice-ops.sh: propose-epic / epic-status / epic-writeback [#62] ══════════════
+# Stub PROPIO (puerto, routes-ep.json y calls-ep.jsonl): routes-cl.json/STUB_CL ya no existen
+# en este punto del fichero y mutarlos rompería aserciones aguas arriba.
+PORT_EP="$(freeport)"
+cat > "$TMP/routes-ep.json" <<JSON
+{"POST /projects/p-1/epic-proposals": {"status": 201, "body": {"proposal_id": "prop-77", "status": "PROPOSED"}}}
+JSON
+: > "$TMP/calls-ep.jsonl"
+python3 "$ROOT/scripts/tests/lib/http-stub.py" "$PORT_EP" "$TMP/routes-ep.json" "$TMP/calls-ep.jsonl" &
+STUB_EP=$!
+STUBS="$STUBS $STUB_EP"
+sleep 0.3
+runtime_credentials_merge "{\"runtime_url\":\"http://127.0.0.1:$PORT_EP\",\"project_token\":\"tok-ep\",\"project_id\":\"p-1\",\"agent_key\":\"ak-1\"}"
+
+# --- [#62] propose-epic ---
+cat > "$TMP/draft.json" <<'JSON'
+{"title":"Notificaciones en tiempo real","objective":"que el usuario vea los avisos sin recargar",
+ "layer":"business","files_scope":["src/notifications/**"],"depends_on":["EP-012"],
+ "epic_code":"EP-999",
+ "stories":[{"title":"ver el aviso","acceptance_criteria":"Dado … Cuando … Entonces …"}]}
+JSON
+
+# legacy y dual: rc 3 sin efectos (ni cola, ni red).
+rm -rf "$PROJ/.claude/state/outbox"; rm -f "$(ops_epic_ledger_path)"
+TRYCORE_RUNTIME_MODE=legacy bash "$SO" propose-epic --file "$TMP/draft.json" >/dev/null 2>&1
+[ $? -eq 3 ] && echo "OK propose-epic rc 3 en legacy" || { echo "FAIL propose-epic legacy"; fail=1; }
+out="$(TRYCORE_RUNTIME_MODE=dual bash "$SO" propose-epic --file "$TMP/draft.json" 2>&1)"; rc=$?
+[ $rc -eq 3 ] && echo "OK propose-epic rc 3 en dual" || { echo "FAIL propose-epic dual"; fail=1; }
+# [Ronda final] En `dual` SÍ hay hub (el proyecto está registrado; el fichero es primario):
+# el mensaje de legacy mandaba a buscar un problema de conexión inexistente.
+echo "$out" | grep -qi 'no hay hub' \
+  && { echo "FAIL propose-epic dice \"no hay hub\" en modo dual"; fail=1; } \
+  || echo "OK propose-epic en dual no niega la existencia del hub"
+echo "$out" | grep -qi 'dual' && echo "OK propose-epic en dual nombra el modo" \
+  || { echo "FAIL el mensaje de dual no nombra el modo: $out"; fail=1; }
+n="$(find "$PROJ/.claude/state/outbox" -maxdepth 1 -name '*.json' 2>/dev/null | wc -l | tr -d ' ')"
+[ "${n:-0}" = 0 ] && echo "OK propose-epic no encola nada en legacy|dual" || { echo "FAIL efectos en legacy|dual"; fail=1; }
+
+# runtime online: se envía y devuelve el identificador del hub.
+out="$(bash "$SO" propose-epic --file "$TMP/draft.json" 2>&1)"; rc=$?
+[ $rc -eq 0 ] && echo "$out" | grep -q 'prop-77' \
+  && echo "OK propose-epic envia y devuelve el identificador" \
+  || { echo "FAIL propose-epic online (rc $rc): $out"; fail=1; }
+
+# El EP-XXX del borrador se IGNORA (la identidad la asigna el hub, hub#113) — ignorar, no rechazar.
+body="$(python3 - "$TMP/calls-ep.jsonl" <<'PY'
+import json,sys
+for l in open(sys.argv[1]):
+    d=json.loads(l)
+    if d["path"]=="/projects/p-1/epic-proposals":
+        b=json.loads(d["body"])
+        print("SI" if "epic_code" not in b and b.get("title","").startswith("Notificaciones") else "NO")
+        break
+PY
+)"
+[ "$body" = SI ] && echo "OK propose-epic ignora el EP-XXX del borrador" \
+  || { echo "FAIL el EP-XXX viajo al hub ($body)"; fail=1; }
+echo "$out" | grep -qi 'ignorado' && echo "OK propose-epic avisa de que ignoro el codigo" \
+  || { echo "FAIL sin aviso del codigo ignorado"; fail=1; }
+
+# El ledger recuerda la propuesta con su borrador.
+ops_epic_ledger_read | python3 -c "
+import json,sys
+p=json.load(sys.stdin)['proposals'][0]
+print('SI' if p['status']=='PROPOSED' and p['proposal_id']=='prop-77' and p['draft']['title'].startswith('Notificaciones') else 'NO')" \
+  | grep -q SI && echo "OK el ledger registra la propuesta enviada" \
+  || { echo "FAIL el ledger no registro la propuesta"; fail=1; }
+
+# Offline: queda encolada y se despacha al reconectar.
+kill "$STUB_EP" 2>/dev/null; wait "$STUB_EP" 2>/dev/null
+out="$(bash "$SO" propose-epic --file "$TMP/draft.json" 2>&1)"; rc=$?
+[ $rc -eq 5 ] && echo "OK propose-epic offline rc 5" || { echo "FAIL propose-epic offline (rc $rc): $out"; fail=1; }
+n="$(find "$PROJ/.claude/state/outbox" -maxdepth 1 -name '*.json' 2>/dev/null | wc -l | tr -d ' ')"
+[ "${n:-0}" -ge 1 ] && echo "OK propose-epic offline deja la propuesta en la cola" \
+  || { echo "FAIL la propuesta offline se perdio"; fail=1; }
+python3 "$ROOT/scripts/tests/lib/http-stub.py" "$PORT_EP" "$TMP/routes-ep.json" "$TMP/calls-ep.jsonl" &
+STUB_EP=$!
+STUBS="$STUBS $STUB_EP"
+sleep 0.3
+rm -f "$PROJ/.claude/state/outbox/.dispatch-state.json"
+runtime_dispatch_outbox >/dev/null 2>&1
+n="$(find "$PROJ/.claude/state/outbox" -maxdepth 1 -name '*.json' 2>/dev/null | wc -l | tr -d ' ')"
+[ "${n:-0}" = 0 ] && echo "OK la propuesta encolada se despacha al reconectar" \
+  || { echo "FAIL la propuesta encolada no se despacho ($n)"; fail=1; }
+
+# Uso: sin --file, rc 2.
+bash "$SO" propose-epic >/dev/null 2>&1
+[ $? -eq 2 ] && echo "OK propose-epic sin --file rc 2" || { echo "FAIL propose-epic uso"; fail=1; }
+# Borrador sin título: rc 2 con mensaje accionable (compuerta local, sin gastar red).
+echo '{"objective":"algo"}' > "$TMP/malo.json"
+out="$(bash "$SO" propose-epic --file "$TMP/malo.json" 2>&1)"
+[ $? -eq 2 ] && echo "$out" | grep -qi 'title' && echo "OK propose-epic valida el borrador en local" \
+  || { echo "FAIL validacion local del borrador: $out"; fail=1; }
+
+# --- [#62] epic-status ---
+python3 - "$TMP/routes-ep.json" <<'PY'
+import json,sys
+p=sys.argv[1]; d=json.load(open(p))
+d["GET /projects/p-1/epic-proposals/prop-77"]={"status":200,"body":{
+  "proposal_id":"prop-77","status":"APPROVED","epic_code":"EP-045",
+  "epic":{"title":"Notificaciones en tiempo real","objective":"que el usuario vea los avisos sin recargar",
+          "layer":"business","depends_on":["EP-012"],
+          "stories":[{"code":"HU-310","title":"ver el aviso"}]}}}
+json.dump(d,open(p,"w"))
+PY
+TRYCORE_RUNTIME_MODE=legacy bash "$SO" epic-status >/dev/null 2>&1
+[ $? -eq 3 ] && echo "OK epic-status rc 3 en legacy" || { echo "FAIL epic-status legacy"; fail=1; }
+out="$(TRYCORE_RUNTIME_MODE=dual bash "$SO" epic-status 2>&1)"; rc=$?
+[ $rc -eq 3 ] && echo "$out" | grep -qi 'dual' \
+  && echo "OK epic-status en dual rc 3 con el texto del modo" \
+  || { echo "FAIL epic-status en dual (rc $rc): $out"; fail=1; }
+
+out="$(bash "$SO" epic-status 2>&1)"; rc=$?
+[ $rc -eq 0 ] && echo "$out" | grep -q 'EP-045' \
+  && echo "OK epic-status resuelve la aprobacion y muestra el codigo" \
+  || { echo "FAIL epic-status (rc $rc): $out"; fail=1; }
+ops_epic_ledger_read | python3 -c "
+import json,sys
+p=json.load(sys.stdin)['proposals'][0]
+print('SI' if p['status']=='APPROVED' and p['epic_code']=='EP-045' and p['epic']['stories'][0]['code']=='HU-310' else 'NO')" \
+  | grep -q SI && echo "OK epic-status guarda el codigo y el contenido aprobado" \
+  || { echo "FAIL el ledger no recogio la aprobacion"; fail=1; }
+
+# Un hub sin soporte (404) se dice con esas palabras y NO rompe nada.
+python3 - "$TMP/routes-ep.json" <<'PY'
+import json,sys
+p=sys.argv[1]; d=json.load(open(p))
+d.pop("GET /projects/p-1/epic-proposals/prop-77",None)
+json.dump(d,open(p,"w"))
+PY
+ops_epic_ledger_upsert '{"client_event_id":"cid-x","proposal_id":"prop-77","status":"PROPOSED"}'
+out="$(bash "$SO" epic-status 2>&1)"; rc=$?
+[ $rc -eq 0 ] && echo "$out" | grep -qi 'sin soporte' \
+  && echo "OK epic-status nombra la falta de soporte del hub" \
+  || { echo "FAIL epic-status con 404 (rc $rc): $out"; fail=1; }
+
+# --- [#62] epic-writeback: el fichero es proyección del grafo, nunca al revés ---
+mkdir -p "$PROJ/docs/03-backlog"
+cat > "$PROJ/docs/03-backlog/epicas.md" <<'MD'
+# Épicas
+
+## EP-012 — Autenticación
+
+**Objetivo**: entrar a la aplicación.
+MD
+# Restaura el ledger con una propuesta APROBADA (el 404 del test anterior no la tocó).
+rm -f "$(ops_epic_ledger_path)"
+ops_epic_ledger_upsert '{"client_event_id":"cid-w","proposal_id":"prop-77","status":"APPROVED",
+ "epic_code":"EP-045","written_back_at":null,
+ "epic":{"title":"Notificaciones en tiempo real","objective":"que el usuario vea los avisos sin recargar",
+ "layer":"business","depends_on":["EP-012"],"stories":[{"code":"HU-310","title":"ver el aviso"},{"title":"marcar como leído"}]}}'
+
+TRYCORE_RUNTIME_MODE=legacy bash "$SO" epic-writeback >/dev/null 2>&1
+[ $? -eq 3 ] && echo "OK epic-writeback rc 3 en legacy" || { echo "FAIL epic-writeback legacy"; fail=1; }
+out="$(TRYCORE_RUNTIME_MODE=dual bash "$SO" epic-writeback 2>&1)"; rc=$?
+[ $rc -eq 3 ] && echo "$out" | grep -qi 'dual' \
+  && echo "OK epic-writeback en dual rc 3 con el texto del modo" \
+  || { echo "FAIL epic-writeback en dual (rc $rc): $out"; fail=1; }
+
+out="$(cd "$PROJ" && bash "$SO" epic-writeback 2>&1)"; rc=$?
+[ $rc -eq 0 ] && echo "$out" | grep -q 'EP-045' \
+  && echo "OK epic-writeback escribe la epica aprobada" || { echo "FAIL epic-writeback (rc $rc): $out"; fail=1; }
+grep -q '^## EP-045 — Notificaciones en tiempo real$' "$PROJ/docs/03-backlog/epicas.md" \
+  && echo "OK el encabezado usa el codigo que asigno el hub" \
+  || { echo "FAIL encabezado del write-back"; fail=1; }
+grep -q 'depende_de: \[EP-012\]' "$PROJ/docs/03-backlog/epicas.md" \
+  && echo "OK el write-back deja depende_de estructurado (lo lee graph-bundle)" \
+  || { echo "FAIL depende_de ausente"; fail=1; }
+grep -q 'origin: harness-writeback' "$PROJ/docs/03-backlog/epicas.md" \
+  && echo "OK el write-back se identifica en el frontmatter" || { echo "FAIL origin ausente"; fail=1; }
+grep -q 'HU-310 — ver el aviso' "$PROJ/docs/03-backlog/epicas.md" \
+  && echo "OK las historias con codigo del hub se escriben con el" \
+  || { echo "FAIL historia con codigo"; fail=1; }
+grep -q '^- marcar como leído$' "$PROJ/docs/03-backlog/epicas.md" \
+  && echo "OK las historias sin codigo se escriben sin inventarlo" \
+  || { echo "FAIL historia sin codigo"; fail=1; }
+python3 -c "
+import re
+t=open('$PROJ/docs/03-backlog/epicas.md').read()
+print(len(re.findall(r'^## EP-045 ', t, re.M)))" | grep -qx 1 \
+  && echo "OK una sola seccion EP-045" || { echo "FAIL secciones duplicadas"; fail=1; }
+
+# [Importante 2] captura el estado del fichero AJENO antes del paso en vacío: ni un byte
+# ni el modo (mkstemp crea con 0600; una reescritura innecesaria degradaría los permisos
+# del backlog del consumidor) ni el inodo deben cambiar cuando no hay nada que escribir.
+before_stat="$(python3 -c "import os; st=os.stat('$PROJ/docs/03-backlog/epicas.md'); print(st.st_ino, oct(st.st_mode))")"
+before_bytes="$(cat "$PROJ/docs/03-backlog/epicas.md")"
+
+# Idempotente: una segunda pasada no duplica y no tiene nada que hacer.
+out="$(cd "$PROJ" && bash "$SO" epic-writeback 2>&1)"; rc=$?
+[ $rc -eq 7 ] && echo "OK epic-writeback rc 7 sin nada pendiente" \
+  || { echo "FAIL epic-writeback repetido (rc $rc): $out"; fail=1; }
+python3 -c "
+import re
+t=open('$PROJ/docs/03-backlog/epicas.md').read()
+print(len(re.findall(r'^## EP-045 ', t, re.M)))" | grep -qx 1 \
+  && echo "OK el write-back es idempotente" || { echo "FAIL el write-back duplico la epica"; fail=1; }
+ops_epic_ledger_read | python3 -c "
+import json,sys
+p=json.load(sys.stdin)['proposals'][0]
+print('SI' if p.get('written_back_at') else 'NO')" | grep -q SI \
+  && echo "OK el ledger marca el write-back hecho" || { echo "FAIL written_back_at sin marcar"; fail=1; }
+
+after_stat="$(python3 -c "import os; st=os.stat('$PROJ/docs/03-backlog/epicas.md'); print(st.st_ino, oct(st.st_mode))")"
+after_bytes="$(cat "$PROJ/docs/03-backlog/epicas.md")"
+[ "$before_stat" = "$after_stat" ] && echo "OK epic-writeback rc 7 no toca inodo/permisos de epicas.md (fichero ajeno intacto)" \
+  || { echo "FAIL epic-writeback rc 7 reescribio epicas.md (antes: $before_stat / despues: $after_stat)"; fail=1; }
+[ "$before_bytes" = "$after_bytes" ] && echo "OK epic-writeback rc 7 no cambia ni un byte de epicas.md" \
+  || { echo "FAIL epic-writeback rc 7 cambio el contenido de epicas.md"; fail=1; }
+
+# [issue #62 · hueco de cobertura] el brief garantiza que graph-bundle.py --from-docs sigue
+# leyendo el bloque que epic-writeback acaba de escribir: se prueba ANTES de que el siguiente
+# bloque borre epicas.md.
+deps_out="$(python3 "$ROOT/scripts/lib/graph-bundle.py" --print-deps "$PROJ/docs/03-backlog/epicas.md" 2>"$TMP/gb-writeback.err")"
+gb_rc=$?
+[ $gb_rc -eq 0 ] && echo "$deps_out" | python3 -c "
+import json,sys
+d=json.load(sys.stdin)
+print('SI' if d.get('EP-045')==['EP-012'] else 'NO')" | grep -q SI \
+  && echo "OK graph-bundle.py --from-docs reconoce la seccion EP-045 escrita por epic-writeback y su dependencia de EP-012" \
+  || { echo "FAIL graph-bundle no leyo el write-back (rc $gb_rc): $deps_out"; fail=1; }
+
+# [Importante 3/4] un fallo de E/S al escribir epicas.md o el ledger se anuncia como fallo,
+# JAMÁS como "nada que escribir" (benigno) ni como éxito con el ledger desincronizado.
+# Se omite bajo root: chmod no restringe la escritura y el fixture no sería significativo.
+if [ "$(id -u)" != 0 ]; then
+  ops_epic_ledger_upsert '{"client_event_id":"cid-io1","proposal_id":"prop-io1","status":"APPROVED",
+   "epic_code":"EP-050","written_back_at":null,
+   "epic":{"title":"Fallo de E-S","objective":"probar el fallo de E-S","layer":"business","depends_on":[]}}'
+
+  # (a) epicas.md no se puede escribir (directorio de solo lectura).
+  chmod 555 "$PROJ/docs/03-backlog"
+  out="$(cd "$PROJ" && bash "$SO" epic-writeback 2>&1)"; rc=$?
+  chmod 755 "$PROJ/docs/03-backlog"
+  [ $rc -eq 5 ] && echo "OK epic-writeback rc 5 si epicas.md no se puede escribir (fallo de E/S, no rc 7)" \
+    || { echo "FAIL epic-writeback con docs de solo lectura (rc $rc): $out"; fail=1; }
+  echo "$out" | grep -qi 'nada que escribir' \
+    && { echo "FAIL el fallo de E/S al escribir epicas.md se reporto como \"nada que escribir\""; fail=1; } \
+    || echo "OK el fallo de E/S al escribir epicas.md NO se confunde con \"nada que escribir\""
+
+  # (b) epicas.md SÍ se puede escribir pero el ledger no (directorio de solo lectura):
+  #     no debe reportarse éxito con el ledger sin persistir.
+  chmod 555 "$PROJ/.claude/state"
+  out2="$(cd "$PROJ" && bash "$SO" epic-writeback 2>&1)"; rc2=$?
+  chmod 755 "$PROJ/.claude/state"
+  [ $rc2 -eq 5 ] && echo "OK epic-writeback rc 5 si el ledger no se puede persistir (no rc 0)" \
+    || { echo "FAIL epic-writeback con ledger de solo lectura (rc $rc2): $out2"; fail=1; }
+  echo "$out2" | grep -q '^escritas en' \
+    && { echo "FAIL reporto \"escritas en...\" (exito) con el ledger sin persistir"; fail=1; } \
+    || echo "OK epic-writeback no reporta exito si el ledger no se pudo persistir"
+
+  # Descarta el fixture: no debe interferir con el resto de la suite.
+  ops_epic_ledger_upsert '{"client_event_id":"cid-io1","status":"REJECTED","reason":"fixture de test descartada"}'
+else
+  echo "OK (omitido bajo root, chmod no restringe) fallo de E/S de epic-writeback en epicas.md"
+  echo "OK (omitido bajo root, chmod no restringe) fallo de E/S de epic-writeback en el ledger"
+fi
+
+# [Ronda final · B4] Un encabezado SANGRADO ya existente cuenta como sección presente: el
+# extractor de graph-bundle.py acepta `\s{0,3}` de sangría y el write-back exigía `#` en
+# columna 0 — el falso negativo DUPLICABA la épica en el fichero.
+cat > "$PROJ/docs/03-backlog/epicas.md" <<'MD'
+# Épicas
+
+  ## EP-060 — Sangrada a mano
+
+**Objetivo**: existir con dos espacios delante.
+MD
+ops_epic_ledger_upsert '{"client_event_id":"cid-ind","proposal_id":"prop-ind","status":"APPROVED",
+ "epic_code":"EP-060","written_back_at":null,
+ "epic":{"title":"Sangrada a mano","objective":"existir con dos espacios delante","layer":"business","depends_on":[]}}'
+out="$(cd "$PROJ" && bash "$SO" epic-writeback 2>&1)"; rc=$?
+[ $rc -eq 7 ] && echo "OK epic-writeback ve la seccion sangrada y no reescribe" \
+  || { echo "FAIL epic-writeback no reconocio el encabezado sangrado (rc $rc): $out"; fail=1; }
+python3 -c "
+import re
+t=open('$PROJ/docs/03-backlog/epicas.md').read()
+print(len(re.findall(r'^\s{0,3}#{1,6}\s+EP-060 ', t, re.M)))" | grep -qx 1 \
+  && echo "OK la epica con encabezado sangrado no se duplica" \
+  || { echo "FAIL el write-back duplico la epica con encabezado sangrado"; fail=1; }
+
+# [Ronda final · A5] `--file` está acotado al carve-out de METODOLOGIA §9.2: el write-back
+# solo escribe bajo docs/03-backlog/. Fuera de ahí, rc 2 accionable y CERO escritura.
+ops_epic_ledger_upsert '{"client_event_id":"cid-scope","proposal_id":"prop-scope","status":"APPROVED",
+ "epic_code":"EP-061","written_back_at":null,
+ "epic":{"title":"Fuera del carve-out","objective":"no debe escribirse fuera","layer":"business","depends_on":[]}}'
+echo "# ajeno" > "$TMP/fuera.md"
+before_fuera="$(cat "$TMP/fuera.md")"
+out="$(cd "$PROJ" && bash "$SO" epic-writeback --file "$TMP/fuera.md" 2>&1)"; rc=$?
+[ $rc -eq 2 ] && echo "OK epic-writeback --file fuera del carve-out da rc 2" \
+  || { echo "FAIL --file fuera del carve-out (rc $rc): $out"; fail=1; }
+echo "$out" | grep -q '03-backlog' && echo "OK el rechazo de --file dice cual es la ruta permitida" \
+  || { echo "FAIL el rechazo de --file no es accionable: $out"; fail=1; }
+[ "$(cat "$TMP/fuera.md")" = "$before_fuera" ] && echo "OK el fichero fuera del carve-out no se toco" \
+  || { echo "FAIL se escribio un fichero fuera del carve-out"; fail=1; }
+# Ni siquiera por travesía: `docs/03-backlog/../../` sale del subárbol.
+out="$(cd "$PROJ" && bash "$SO" epic-writeback --file "$PROJ/docs/03-backlog/../../fuera-travesia.md" 2>&1)"; rc=$?
+[ $rc -eq 2 ] && echo "OK epic-writeback rechaza la travesia con .." \
+  || { echo "FAIL la travesia con .. escapo del carve-out (rc $rc): $out"; fail=1; }
+# Dentro del carve-out, un fichero distinto de epicas.md SÍ se acepta (el backlog puede estar partido).
+cat > "$PROJ/docs/03-backlog/epicas-extra.md" <<'MD'
+# Épicas (anexo)
+MD
+out="$(cd "$PROJ" && bash "$SO" epic-writeback --file "$PROJ/docs/03-backlog/epicas-extra.md" 2>&1)"; rc=$?
+[ $rc -eq 0 ] && echo "$out" | grep -q 'EP-061' \
+  && echo "OK epic-writeback acepta otra ruta DENTRO de docs/03-backlog/" \
+  || { echo "FAIL --file dentro del carve-out (rc $rc): $out"; fail=1; }
+grep -q '^## EP-061 — Fuera del carve-out$' "$PROJ/docs/03-backlog/epicas-extra.md" \
+  && echo "OK la epica se escribio en el fichero permitido" \
+  || { echo "FAIL no se escribio en el fichero permitido"; fail=1; }
+
+# Sin fichero de épicas: rc 4 accionable, no un traceback.
+rm -f "$PROJ/docs/03-backlog/epicas.md"
+ops_epic_ledger_upsert '{"client_event_id":"cid-w","written_back_at":null}'
+out="$(cd "$PROJ" && bash "$SO" epic-writeback 2>&1)"; rc=$?
+[ $rc -eq 4 ] && echo "OK epic-writeback rc 4 sin fichero de epicas" \
+  || { echo "FAIL epic-writeback sin fichero (rc $rc): $out"; fail=1; }
+
 # ══════════════ scripts/lib/graph-bundle.py [Task 13 · issue #41] ══════════════
 GB="$ROOT/scripts/lib/graph-bundle.py"
 cat > "$TMP/epics.json" <<'JSON'
@@ -1593,4 +1981,190 @@ echo 'no-json' | python3 "$GB" > /dev/null 2> "$TMP/gb3.err"
 rc=$?
 [ "$rc" = 1 ] && ! grep -q "Traceback" "$TMP/gb3.err" && echo "OK graph-bundle con entrada ilegible -> rc 1 limpio" || { echo "FAIL entrada ilegible ($rc)"; fail=1; }
 
+# ══════════ graph-bundle.py --from-docs / --print-deps [issue #56] ══════════
+# El grafo llegaba al hub con `depends_on: []` (41/41 épicas en el piloto): la
+# extracción vivía en el LLM y el ejemplo de onboard anclaba en []. El extractor
+# es ahora DETERMINISTA y lee la prosa de `docs/03-backlog/epicas.md`.
+mkdir -p "$TMP/docs"
+cat > "$TMP/docs/epicas.md" <<'MD'
+# Backlog — épicas
+
+**Dependencias entre épicas**: EP-999 (esto está FUERA de toda sección: se ignora)
+
+## EP-001 — Cimiento
+
+**Depende de**: nada.
+
+**Resumen**: base técnica.
+
+---
+
+## EP-002 — Cobros
+
+**Anexo A**: Fase 3 · **Depende de**: **EP-001** (base de datos), EP-404 (no existe en el grafo)
+
+**Resumen**: cobra.
+
+## EP-003 — Reportes
+
+**Depende de**: EP-002 (pipeline de export),
+EP-001 (cimiento). Ninguna bloquea: todas archivadas.
+
+**Resumen**: reporta.
+
+## EP-004 — Estructurada
+
+depende_de: [EP-003]
+
+**Depende de**: EP-001 en prosa — gana el campo estructurado.
+
+## EP-005 — Autorreferente
+
+**Depende de**: EP-005 (a sí misma: se excluye), EP-001
+MD
+
+# 1) --print-deps: extracción pura, determinista, inspeccionable.
+out="$(python3 "$GB" --print-deps "$TMP/docs/epicas.md" 2> "$TMP/gb4.err")"
+rc=$?
+# `**Depende de**: nada.` es una declaración, no una ausencia: entra con lista vacía.
+esperado='{"EP-001": [], "EP-002": ["EP-001", "EP-404"], "EP-003": ["EP-001", "EP-002"], "EP-004": ["EP-003"], "EP-005": ["EP-001"]}'
+[ "$rc" = 0 ] && [ "$(echo "$out" | python3 -c 'import json,sys;print(json.dumps(json.load(sys.stdin),sort_keys=True))')" = "$esperado" ] \
+  && echo "OK --print-deps extrae de la prosa (multilínea, campo estructurado, sin autorreferencia)" \
+  || { echo "FAIL --print-deps ($rc) -> $out"; fail=1; }
+
+# 2) --from-docs puebla el grafo aunque el JSON del modelo traiga depends_on vacíos.
+cat > "$TMP/epics56.json" <<'JSON'
+{"project_ref":"acme","epics":[
+  {"code":"EP-001","title":"Cimiento","layer":"foundational","depends_on":[]},
+  {"code":"EP-002","title":"Cobros","layer":"business","depends_on":[]},
+  {"code":"EP-003","title":"Reportes","layer":"business","depends_on":[]},
+  {"code":"EP-004","title":"Estructurada","layer":"business","depends_on":["EP-002"]}
+]}
+JSON
+out="$(python3 "$GB" --from-docs "$TMP/docs/epicas.md" < "$TMP/epics56.json" 2> "$TMP/gb5.err")"
+rc=$?
+[ "$rc" = 0 ] && [ "$(echo "$out" | python3 -c 'import json,sys;d=json.load(sys.stdin);print(";".join(e["code"]+"="+",".join(e["depends_on"]) for e in d["epics"]))')" = "EP-001=;EP-002=EP-001,EP-404;EP-003=EP-001,EP-002;EP-004=EP-002,EP-003" ] \
+  && echo "OK --from-docs puebla depends_on desde los docs (unión con lo declarado)" \
+  || { echo "FAIL --from-docs ($rc) -> $out"; fail=1; }
+grep -q "EP-404" "$TMP/gb5.err" \
+  && echo "OK --from-docs mantiene el aviso de dependencia inexistente" || { echo "FAIL sin aviso de dep inexistente con --from-docs"; fail=1; }
+grep -q "EP-005" "$TMP/gb5.err" \
+  && echo "OK --from-docs avisa de la épica que está en docs pero no en el JSON" || { echo "FAIL sin aviso de épica ausente del JSON"; fail=1; }
+echo "$out" | grep -q '"depends_on_source"' \
+  && echo "OK el bundle deja traza de la fuente de dependencias" || { echo "FAIL el bundle no declara depends_on_source"; fail=1; }
+
+# 3) Los ciclos que vienen de la prosa se cazan igual (el aviso ya existía).
+cat > "$TMP/docs/ciclo.md" <<'MD'
+## EP-010 — A
+**Depende de**: EP-011
+## EP-011 — B
+**Depende de**: EP-010
+MD
+echo '{"epics":[{"code":"EP-010","title":"A","layer":"business"},{"code":"EP-011","title":"B","layer":"business"}]}' \
+  | python3 "$GB" --from-docs "$TMP/docs/ciclo.md" > /dev/null 2> "$TMP/gb6.err"
+rc=$?
+[ "$rc" = 0 ] && grep -qi "ciclo" "$TMP/gb6.err" \
+  && echo "OK --from-docs + ciclo de la prosa -> aviso, sin bloquear" || { echo "FAIL ciclo desde docs ($rc)"; fail=1; }
+
+# 4) Ruta ilegible: rc 1 con mensaje, jamás traceback ni silencio (el fallo del piloto
+#    fue precisamente un grafo vacío que no falló).
+echo '{"epics":[]}' | python3 "$GB" --from-docs "$TMP/docs/no-existe.md" > /dev/null 2> "$TMP/gb7.err"
+rc=$?
+[ "$rc" = 1 ] && ! grep -q "Traceback" "$TMP/gb7.err" \
+  && echo "OK --from-docs con ruta ilegible -> rc 1 limpio" || { echo "FAIL ruta ilegible ($rc)"; fail=1; }
+# Flag sin argumento: mismo trato.
+echo '{"epics":[]}' | python3 "$GB" --from-docs > /dev/null 2> "$TMP/gb8.err"
+[ "$?" = 1 ] && ! grep -q "Traceback" "$TMP/gb8.err" \
+  && echo "OK --from-docs sin argumento -> rc 1 limpio" || { echo "FAIL --from-docs sin argumento"; fail=1; }
+
+# 4-bis) Sección presente pero SIN el campo: aviso distinto al de sección ausente
+#        (un backlog que dibuja sus dependencias en ASCII no es un backlog sin épicas).
+printf '## EP-020 — Con seccion, sin campo\n\n**Resumen**: x.\n' > "$TMP/docs/sin-campo.md"
+echo '{"epics":[{"code":"EP-020","title":"X","layer":"business"},{"code":"EP-021","title":"Y","layer":"business"}]}' \
+  | python3 "$GB" --from-docs "$TMP/docs/sin-campo.md" > /dev/null 2> "$TMP/gb10.err"
+grep -q "EP-020 tiene sección" "$TMP/gb10.err" && grep -q "EP-021 no aparece como sección" "$TMP/gb10.err" \
+  && echo "OK distingue sección sin campo de épica ausente de los docs" || { echo "FAIL avisos de cobertura de docs"; fail=1; }
+
+# 4-ter) Las dos banderas juntas son un error explícito (ignorar una en silencio es el
+#        patrón que causó #56).
+echo '{"epics":[]}' | python3 "$GB" --from-docs "$TMP/docs/epicas.md" --print-deps "$TMP/docs/epicas.md" > /dev/null 2> "$TMP/gb11.err"
+[ "$?" = 1 ] && grep -qi "excluyentes" "$TMP/gb11.err" \
+  && echo "OK --from-docs y --print-deps juntas -> rc 1 explícito" || { echo "FAIL banderas excluyentes"; fail=1; }
+
+# 5) Sin sección de épica reconocible: aviso explícito (no silencio).
+printf 'texto sin encabezados de epica\n' > "$TMP/docs/vacio.md"
+echo '{"epics":[{"code":"EP-001","title":"X","layer":"business"}]}' \
+  | python3 "$GB" --from-docs "$TMP/docs/vacio.md" > /dev/null 2> "$TMP/gb9.err"
+grep -qi "ninguna secci" "$TMP/gb9.err" \
+  && echo "OK avisa cuando los docs no traen secciones de épica" || { echo "FAIL sin aviso de docs sin épicas"; fail=1; }
+
+# ══════════════ slice-ops.sh: claim manda la version de grafo [#63] ══════════════
+# Stub PROPIO (puerto, routes-gv.json y calls-gv.jsonl): routes-cl.json/STUB_CL ya no existen
+# en este punto del fichero y mutarlos rompería aserciones aguas arriba (Ruling R3/R4).
+PORT_GV="$(freeport)"
+cat > "$TMP/routes-gv.json" <<JSON
+{"GET /agent/context": {"status": 200, "body": {"project": {}, "active_slice": {}, "nudges": [],
+  "context": {"manifest_hash": "sha256:v2", "version": 9, "graph_version": 45}}},
+ "POST /tasks/next": {"status": 409, "body": {"reason": "stale_graph", "graph_version": 45}}}
+JSON
+: > "$TMP/calls-gv.jsonl"
+python3 "$ROOT/scripts/tests/lib/http-stub.py" "$PORT_GV" "$TMP/routes-gv.json" "$TMP/calls-gv.jsonl" &
+STUB_GV=$!
+STUBS="$STUBS $STUB_GV"
+sleep 0.3
+runtime_credentials_merge "{\"runtime_url\":\"http://127.0.0.1:$PORT_GV\",\"project_token\":\"tok-gv\",\"project_id\":\"p-1\",\"agent_key\":\"ak-1\",\"manifest_hash\":\"sha256:v2\"}"
+
+# --- [#63] claim manda la versión de grafo y trata el 409 como refresco ---
+runtime_projection_write '{"fetched_at":"2099-01-01T00:00:00Z","active_slice":null,"nudges":[],"context":{"manifest_hash":"sha256:v2","version":9,"graph_version":42}}'
+: > "$TMP/calls-gv.jsonl"
+out="$(bash "$SO" claim 2>&1)"; rc=$?
+sent="$(python3 - "$TMP/calls-gv.jsonl" <<'PY'
+import json,sys
+for l in open(sys.argv[1]):
+    d=json.loads(l)
+    if d["path"]=="/tasks/next":
+        print(json.loads(d["body"]).get("graph_version"))
+        break
+PY
+)"
+[ "$sent" = 42 ] && echo "OK claim manda la version de grafo conocida" \
+  || { echo "FAIL claim sin version de grafo ($sent)"; fail=1; }
+n="$(grep -c '"path": "/tasks/next"' "$TMP/calls-gv.jsonl" | tr -d ' ')"
+[ "$n" = 2 ] && echo "OK un 409 stale_graph provoca refresco y UN reintento" \
+  || { echo "FAIL reintentos del 409 stale_graph ($n)"; fail=1; }
+# [Ronda de arreglo 1, Minor 8] '45' y 'grafo' sueltos también los satisface el mensaje del
+# PRIMER 409 (_claim_once), que ya sale por stderr en el mismo $out combinado — no discriminan
+# nada salvo el rc. Se ancla a una frase exclusiva del SEGUNDO mensaje (cmd_claim).
+[ $rc -eq 6 ] && echo "$out" | grep -q '45' && echo "$out" | grep -qi 'incluso tras refrescar' \
+  && echo "OK el segundo 409 nombra el desfase y la accion" \
+  || { echo "FAIL mensaje del segundo 409 (rc $rc): $out"; fail=1; }
+runtime_graph_status_read | python3 -c "
+import json,sys; print(json.load(sys.stdin).get('server'))" | grep -qx 45 \
+  && echo "OK el desfase queda registrado para status" || { echo "FAIL desfase sin registrar"; fail=1; }
+
+# Un hub que no versiona: el cuerpo NO lleva graph_version y el claim funciona igual.
+python3 - "$TMP/routes-gv.json" <<'PY'
+import json,sys
+p=sys.argv[1]; d=json.load(open(p))
+d["POST /tasks/next"]={"status":204,"body":{}}
+d["GET /agent/context"]["body"]["context"].pop("graph_version",None)
+json.dump(d,open(p,"w"))
+PY
+runtime_projection_write '{"fetched_at":"2099-01-01T00:00:00Z","active_slice":null,"nudges":[],"context":{"manifest_hash":"sha256:v2","version":9}}'
+: > "$TMP/calls-gv.jsonl"
+bash "$SO" claim >/dev/null 2>&1; rc=$?
+has="$(python3 - "$TMP/calls-gv.jsonl" <<'PY'
+import json,sys
+for l in open(sys.argv[1]):
+    d=json.loads(l)
+    if d["path"]=="/tasks/next":
+        print("SI" if "graph_version" in json.loads(d["body"]) else "NO")
+        break
+PY
+)"
+[ "$has" = NO ] && [ $rc -eq 7 ] && echo "OK sin hub que versione, el claim no manda nada nuevo" \
+  || { echo "FAIL compatibilidad hacia atras del claim (has=$has rc=$rc)"; fail=1; }
+
+kill "$STUB_GV" 2>/dev/null; wait "$STUB_GV" 2>/dev/null
+
 exit $fail