@trycore/spec-build-harness 0.13.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'
@@ -1710,5 +2098,73 @@ echo '{"epics":[{"code":"EP-001","title":"X","layer":"business"}]}' \
 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

package/skills/building-a-slice/references/dor.md

@@ -11,15 +11,27 @@ la épica; lo de abajo aplica a la épica y a **cada HU** que cubre (`hus[]`). L
 - [ ] **Dependencias resueltas**: las épicas/HU de las que depende están archivadas (`history[]`) o explícitamente no bloquean. **Excepción dura — cimiento:** si la dependencia es **infraestructura fundacional** (autenticación, acceso a datos, arquitectura base, design-system/componentes base), la cláusula "explícitamente no bloquean" **NO aplica**: debe estar **construida y archivada** antes (ver criterio "Cimiento construido").
 - [ ] **Cimiento construido (épicas de negocio)**: si esta épica es `layer: business`, todo el cimiento que arrastra (auth, acceso a datos, arquitectura base, design-system/componentes base) ya existe como épica(s) `layer: foundational` **archivada(s)** en `history[]`. Si arrastra cimiento no construido → **STOP**: extráelo a una épica fundacional previa y constrúyela primero. Las épicas fundacionales se priorizan **antes** que las de negocio.
 - [ ] **Caparazón construido (solo greenfield — gate PROACTIVO)**: si `project_kind === "greenfield"`
-  y `foundation.required === true` en los hechos de proyecto del runtime (`slice-ops.sh status`; en modo legacy, `build-state.json`), ninguna épica `layer: business` entra a
-  construcción mientras la épica caparazón (`foundation.epic`) no esté **archivada con su checklist
-  evidenciada** (`foundation.completed_at` estampado). Las épicas `layer: foundational` (la
-  caparazón `foundation.epic` u otras fundacionales) sí pueden abrir. A diferencia de "Cimiento
-  construido" (reactivo: bloquea si *detecta* arrastre), este criterio bloquea **siempre** en
-  greenfield hasta que el cimiento exista archivado — no depende de detectar nada. Si
-  `foundation.epic` es `null` (no existe la épica caparazón aún) → **STOP**: se define en
-  `/build:onboard` Fase 2c o en discovery. Brownfield / `foundation.required: false` → **N/A** (no
-  bloquea). Contrato: `references/foundation-contract.md`.
+  y la caparazón está **requerida**, ninguna épica `layer: business` entra a construcción mientras
+  la caparazón no esté **construida y archivada con su checklist evidenciada**. Las épicas
+  `layer: foundational` (la caparazón u otras fundacionales) sí pueden abrir. A diferencia de
+  "Cimiento construido" (reactivo: bloquea si *detecta* arrastre), este criterio bloquea
+  **siempre** en greenfield hasta que el cimiento exista archivado — no depende de detectar nada.
+  **Dónde se leen esos hechos depende del modo**, y no son los mismos:
+  - **`legacy`/`dual`** — `build-state.json`: `foundation.required`, `foundation.epic` (el
+    `EP-XXX` concreto) y `foundation.completed_at`. Si `foundation.epic` es `null` → **STOP**: la
+    épica caparazón no existe aún; se define en `/build:onboard` Fase 2c o en discovery.
+  - **`runtime`** — la proyección solo trae `foundation_done` (booleano), vía
+    `slice-ops.sh status` (línea `hechos:`). **Nadie fija `foundation.epic` en este modo**: la
+    Fase 2c propone la épica al hub sin código y la identidad la asigna el hub al aprobar
+    (issue #62). Así que aquí **no preguntes por `foundation.epic`** — no existe. Con
+    `foundation_done: false`, el estado real de la caparazón lo dice `slice-ops.sh epic-status`
+    (o `/build:epic --check`): si hay una propuesta `PROPOSED`, el STOP es **esperar la
+    aprobación**, no re-onboardear (repetir la Fase 2c propondría la misma épica dos veces); si
+    no hay ninguna propuesta, entonces sí → Fase 2c o discovery.
+
+  Brownfield o caparazón no requerida (`foundation.required: false` en `legacy`/`dual`;
+  `foundation_done: true` en `runtime`) → **N/A** (no bloquea).
+  Contrato: `references/foundation-contract.md`.
 - [ ] **Tamaño acotado (gate de descomposición)**: si la épica supera el umbral —heurística por defecto **> 3 HU** ó **≥ 3 capas tocadas** (configurable por proyecto)— **no entra como slice único**: se descompone en `sub_slices[]` verificables construidos de a uno, con `journey_smoke` verde entre cada uno. El umbral es proporcional (no cuota rígida): una épica de 1 capa y pocas HU entra directa.
 - [ ] **Cabe en el stack** del PRD §7 (no requiere tecnología fuera de `stack-allowlist.json`).
 - [ ] **Cobertura arquitectónica (ADR)** *(opt-in, retrocompatible)*: si el proyecto adoptó la capa de

package/skills/building-a-slice/references/foundation-contract.md

@@ -40,5 +40,9 @@ N/A y el arnés no pregunta ni exige nada (`foundation.required: false`).
 - El arnés **propone** el borrador de la épica caparazón; **solo** lo escribe en
   `docs/03-backlog/epicas.md` con aprobación humana explícita (carve-out acotado, ver
   METODOLOGIA §9.2). Si el humano rechaza, STOP: la épica se crea en discovery (`/trycore:*`).
+  En modo `runtime`, esa aprobación humana en `/build:onboard` **propone al hub**
+  (`slice-ops.sh propose-epic`), no escribe: el fichero se escribe después, cuando el hub
+  también aprueba y asigna el `EP-XXX`, vía `/build:epic --check` (issue #62). En `legacy`/`dual`
+  la aprobación humana escribe directo, como arriba.
 - La evidencia es de **ejecución**, nunca de inspección.
 - Si contradice `METODOLOGIA.md`, gana la metodología.

package/state/README.md

@@ -141,3 +141,15 @@ El razonamiento vive en el modelo; el hook solo es un recordatorio determinista.
 | `foundation.checklist[].evidence` | `build-orchestrator` (durante la construcción de la caparazón) | al construir la caparazón |
 | `foundation.completed_at` | `dor-dod-gatekeeper` (al cerrar el DoD de la épica caparazón) | al archivar la caparazón |
 | `design_source` (`source`, `confirmed`, `confirmed_by/at`, `notes`) | `building-a-slice` Fase 0-bis · `/build:onboard` Fase 3c · `prototyping-screens` (greenfield, solo tras aprobación humana de ≥1 pantalla; `confirmed` humano siempre) | una vez (proyecto) |
+
+### Ficheros de estado aparte (no viven en `build-state.json`)
+
+La tabla de arriba describe **campos** de `build-state.json`. Estos son **ficheros propios** de
+`.claude/state/`: estado derivado del hub que solo existe en modo `runtime`, no forma parte de la
+máquina del pipeline y por eso no entra en el schema del estado. `trycore-build init` los siembra
+en `.gitignore`.
+
+| Fichero | Lo escribe | Cadencia |
+|---|---|---|
+| `epic-proposals.json` — ledger de propuestas de épica (`client_event_id`, `proposal_id`, `status`, `epic_code`, `draft`, `written_back_at`) | `slice-ops.sh propose-epic` / `epic-status` / `epic-writeback` | por propuesta de épica |
+| `graph-status.json` — marcador de desfase de grafo (`local`, `server`, `seen_at`): lo deja un `409 stale_graph` del hub y **su existencia es la señal** (el fichero se borra en cuanto la acción vuelve a pasar). Es lo que hace **visible** el desfase en `slice-ops.sh status` y `trycore-build status`; sin él el 409 se resolvería solo y nadie sabría que ocurrió. `local: null` = la petición salió sin versión estampada — nunca `0`, que sería una versión real | `runtime_graph_note_stale` / `runtime_graph_clear_stale` (`hooks/build/lib/runtime-client.sh`), desde `slice-ops.sh claim` y desde el despacho del carril directo | por rechazo `409 stale_graph` |