@trycore/spec-build-harness 0.14.2 → 0.15.0

package/scripts/lib/graph-bundle.py

@@ -21,10 +21,17 @@ grafo de forma DETERMINISTA — regex de códigos `EP-…` sobre el campo `Depen
 sección de épica, excluyendo la propia — y lo une a lo que traiga el JSON de entrada. Si la
 épica declara el campo estructurado `depende_de: [EP-001, …]`, ese gana sobre la prosa.
 
+[EP-OR-17] `--for-sync` emite la PROYECCIÓN DE CONTRATO del carril `graph-sync`: `{"epics":[…]}`
+y nada más (`GraphSyncBundle` es `extra="forbid"`; las claves de preparación son un 422). En ese
+modo lo que aquí es aviso pasa a ser RECHAZO con rc 2 — el import de admin lo revisa un humano
+antes de subirlo, pero una propuesta de re-sync viaja sola, y el hub rechaza el grafo ENTERO ante
+una sola épica mal formada.
+
 Uso:
     python3 graph-bundle.py < epics.json > bundle.json      # avisos por stderr
     python3 graph-bundle.py --from-docs docs/03-backlog/epicas.md < epics.json > bundle.json
     python3 graph-bundle.py --print-deps docs/03-backlog/epicas.md   # solo el grafo extraído
+    python3 graph-bundle.py --for-sync --from-docs docs/03-backlog/epicas.md < epics.json
 
 Entrada (stdin, JSON — formato de discovery, sin cambios):
     {"project_ref": "…",
@@ -38,7 +45,9 @@ el criterio del arnés — nada se pierde en silencio, nada bloquea la preparaci
 
 Códigos de salida: 0 = bundle generado (con o sin avisos) · 1 = entrada ilegible
 (incluye una ruta `--from-docs` que no se puede leer: se pidió extraer y no se pudo, y un
-grafo sin aristas no falla solo — empobrece en silencio, que es justo lo que causó #56).
+grafo sin aristas no falla solo — empobrece en silencio, que es justo lo que causó #56)
+· 2 = solo con `--for-sync`: el bundle no cumple el contrato del hub (un motivo por línea en
+stderr, cada uno nombrando la épica y el campo).
 """
 import json
 import re
@@ -127,11 +136,15 @@ def leer_dependencias_de_docs(ruta):
 
 
 def parsear_argumentos(argv):
-    """({from_docs, print_deps}, error) — sin dependencias, mismo estilo que el resto."""
-    opciones = {"from_docs": None, "print_deps": None}
+    """({from_docs, print_deps, for_sync}, error) — sin dependencias, mismo estilo que el resto."""
+    opciones = {"from_docs": None, "print_deps": None, "for_sync": False}
     i = 0
     while i < len(argv):
         arg = argv[i]
+        if arg == "--for-sync":
+            opciones["for_sync"] = True
+            i += 1
+            continue
         if arg in ("--from-docs", "--print-deps"):
             if i + 1 >= len(argv) or argv[i + 1].startswith("--"):
                 return opciones, "%s exige la ruta del fichero de épicas" % arg
@@ -145,6 +158,100 @@ def parsear_argumentos(argv):
     return opciones, None
 
 
+# ── Proyección de contrato para el carril `graph-sync` [EP-OR-17] ─────────────────────
+# `GraphSyncBundle` (event_catalog.py del hub) es `extra="forbid"` y admite SOLO `epics`: las
+# claves de preparación (`bundle_version`, `kind`, `project_ref`, `generated_at`,
+# `generated_by`, `depends_on_source`, `warnings`) son un 422 garantizado.
+#
+# Y aquí los avisos se vuelven RECHAZOS. El bundle de preparación puede seguir adelante con
+# `layer` ausente porque un ADMIN lo revisa antes de subirlo; el carril de sync no tiene humano
+# en medio, y el hub rechaza el grafo ENTERO ante una sola épica mal formada. Un aviso que nadie
+# lee es un 422 con pasos extra.
+MAX_EPICAS = 200
+MAX_HISTORIAS = 100
+MAX_FILES_SCOPE = 200
+MAX_DEPENDS_ON = 50
+LARGOS = {"code": 50, "title": 300, "release_line": 100, "docs_ref": 500,
+          "files_scope_item": 500, "depends_on_item": 50}
+
+
+def emitir_para_sync(epicas):
+    """Imprime `{"epics":[…]}` en el formato del contrato; rc 2 si algo no lo cumple."""
+    errores = []
+    if not epicas:
+        errores.append("el bundle no tiene ni una épica: no hay nada que proponer")
+    if len(epicas) > MAX_EPICAS:
+        errores.append("%d épicas: el contrato admite %d como máximo"
+                       % (len(epicas), MAX_EPICAS))
+    salida = []
+    for code in sorted(epicas):
+        e = epicas[code]
+        if len(code) > LARGOS["code"]:
+            errores.append("%s: el `code` excede %d caracteres" % (code, LARGOS["code"]))
+        if not e.get("title"):
+            errores.append("%s: sin `title` (el contrato lo exige no vacío)" % code)
+        elif len(e["title"]) > LARGOS["title"]:
+            errores.append("%s: el `title` excede %d caracteres" % (code, LARGOS["title"]))
+        if e.get("layer") not in VALID_LAYERS:
+            errores.append("%s: `layer` es %r y el contrato exige FOUNDATIONAL o BUSINESS "
+                           "(declárala en los docs de discovery)" % (code, e.get("layer")))
+        fs = e.get("files_scope") or []
+        if len(fs) > MAX_FILES_SCOPE:
+            errores.append("%s: %d entradas en `files_scope` y el contrato admite %d"
+                           % (code, len(fs), MAX_FILES_SCOPE))
+        for x in fs:
+            if not x or len(x) > LARGOS["files_scope_item"]:
+                errores.append("%s: una entrada de `files_scope` está vacía o excede %d "
+                               "caracteres" % (code, LARGOS["files_scope_item"]))
+                break
+        deps = e.get("depends_on") or []
+        if len(deps) > MAX_DEPENDS_ON:
+            errores.append("%s: %d entradas en `depends_on` y el contrato admite %d"
+                           % (code, len(deps), MAX_DEPENDS_ON))
+        for x in deps:
+            if not x or len(x) > LARGOS["depends_on_item"]:
+                errores.append("%s: una entrada de `depends_on` está vacía o excede %d "
+                               "caracteres" % (code, LARGOS["depends_on_item"]))
+                break
+        historias = e.get("stories") or []
+        if len(historias) > MAX_HISTORIAS:
+            errores.append("%s: %d historias y el contrato admite %d por épica"
+                           % (code, len(historias), MAX_HISTORIAS))
+        hs = []
+        for h in historias:
+            hcode = h.get("code") or ""
+            if not hcode or len(hcode) > LARGOS["code"]:
+                errores.append("%s: una historia no tiene `code` o excede %d caracteres"
+                               % (code, LARGOS["code"]))
+                continue
+            htitle = h.get("title") or ""
+            if not htitle:
+                errores.append("%s: la historia %s no tiene `title`" % (code, hcode))
+                continue
+            hs.append({"code": hcode, "title": htitle[:LARGOS["title"]]})
+        proyectada = {"code": code, "title": (e.get("title") or "")[:LARGOS["title"]],
+                      "layer": e.get("layer"),
+                      "files_scope": fs, "depends_on": deps, "stories": hs}
+        # Opcionales: solo viajan si tienen valor. `null` es legal en el contrato, pero omitirlos
+        # deja más corto el delta que el humano revisa en la consola.
+        if e.get("release_line"):
+            proyectada["release_line"] = e["release_line"][:LARGOS["release_line"]]
+        if isinstance(e.get("priority"), int):
+            proyectada["priority"] = e["priority"]
+        if e.get("docs_ref"):
+            proyectada["docs_ref"] = e["docs_ref"][:LARGOS["docs_ref"]]
+        salida.append(proyectada)
+    if errores:
+        print("graph-bundle --for-sync: el bundle NO cumple el contrato del hub "
+              "(no se envía nada):", file=sys.stderr)
+        for x in errores:
+            print("  ⛔ %s" % x, file=sys.stderr)
+        return 2
+    json.dump({"epics": salida}, sys.stdout, indent=2, ensure_ascii=False)
+    sys.stdout.write("\n")
+    return 0
+
+
 def main():
     avisos = []
     opciones, error = parsear_argumentos(sys.argv[1:])
@@ -322,6 +429,14 @@ def main():
                               "(el hub guarda UNA línea por épica)"
                               % (c, epicas[c]["release_line"], r["id"]))
 
+    # [EP-OR-17] El carril de sync se lleva la proyección de contrato y NADA más: los avisos
+    # siguen saliendo por stderr (arriba se han ido acumulando), pero el `warnings` del bundle
+    # de preparación no existe en `GraphSyncBundle` y viajaría como un 422.
+    if opciones["for_sync"]:
+        for a in avisos:
+            print("aviso: %s" % a, file=sys.stderr)
+        return emitir_para_sync(epicas)
+
     bundle = {
         "bundle_version": BUNDLE_VERSION,
         "kind": "graph",

package/scripts/tests/test-install.sh

@@ -177,8 +177,9 @@ fi
 # grafo son estado derivado del hub, igual que los de arriba: mismo blindaje.
 if [ -f "$GI" ] \
   && grep -q '^\.claude/state/epic-proposals\.json$' "$GI" \
+  && grep -q '^\.claude/state/graph-sync-proposals\.json$' "$GI" \
   && grep -q '^\.claude/state/graph-status\.json$' "$GI"; then
-  echo "OK install: .gitignore protege epic-proposals/graph-status"
+  echo "OK install: .gitignore protege epic-proposals/graph-sync-proposals/graph-status"
 else
   echo "FAIL install: .gitignore no protege epic-proposals.json/graph-status.json"
   fail=1

package/scripts/tests/test-runtime-client.sh

@@ -320,6 +320,23 @@ echo '{"title":"Notificaciones","objective":"avisar al usuario"}' > "$TMP/prop.j
 CID="$(runtime_enqueue_direct epic_proposed POST /projects/p-1/epic-proposals "$TMP/prop.json")"
 [ -n "$CID" ] && echo "OK runtime_enqueue_direct devuelve el client_event_id" \
   || { echo "FAIL runtime_enqueue_direct sin id"; fail=1; }
+
+# [EP-OR-17] El cid FIJABLE es lo que hace idempotente el reintento del re-sync: el hub
+# deduplica por client_event_id, así que re-encolar tras un 409 no crea una segunda propuesta.
+cid_fijo="$(runtime_enqueue_direct graph_sync_proposed POST /p/1 "$TMP/prop.json" 1 "ak-1:graph-sync:3")"
+[ "$cid_fijo" = "ak-1:graph-sync:3" ] \
+  && echo "OK enqueue_direct devuelve el cid fijado" \
+  || { echo "FAIL cid fijado ('$cid_fijo')"; fail=1; }
+n_fijo="$(grep -l '"client_event_id": "ak-1:graph-sync:3"' "$CLAUDE_PROJECT_DIR/.claude/state/outbox"/*.json 2>/dev/null | wc -l | tr -d ' ')"
+[ "$n_fijo" = 1 ] && echo "OK el cid fijado se persiste en el fichero encolado" \
+  || { echo "FAIL cid no persistido ($n_fijo)"; fail=1; }
+cid_uuid="$(runtime_enqueue_direct graph_sync_proposed POST /p/1 "$TMP/prop.json" 1)"
+[ -n "$cid_uuid" ] && [ "$cid_uuid" != "ak-1:graph-sync:3" ] \
+  && echo "OK sin 6º argumento sigue generando uuid (carril de épicas intacto)" \
+  || { echo "FAIL regresión del uuid ('$cid_uuid')"; fail=1; }
+# Los dos encolados de prueba se retiran: los bloques de abajo cuentan ficheros de la cola.
+rm -f "$CLAUDE_PROJECT_DIR/.claude/state/outbox"/*"$cid_fijo".json \
+      "$CLAUDE_PROJECT_DIR/.claude/state/outbox"/*"$cid_uuid".json
 f="$(find "$CLAUDE_PROJECT_DIR/.claude/state/outbox" -maxdepth 1 -name '*.json' | head -1)"
 python3 -c "
 import json
@@ -490,10 +507,37 @@ PY
 )"
 [ "$has" = NO ] && echo "OK sin estampado pedido, el cuerpo no cambia" || { echo "FAIL estampado no pedido"; fail=1; }
 
-# 409 stale_graph en el carril directo: se anota el desfase y la petición SIGUE en la cola
-# (la refresca el heartbeat, #61), no se pierde ni se aparta a la primera.
+# [EP-OR-17] El hub NUNCA responde `reason: stale_graph`: emite
+# `{"detail":{"error":"graph_version_stale","graph_version":N}}` (un HTTPException de FastAPI
+# anida SIEMPRE bajo `detail`). El helper acepta las dos formas — la real y la plana legacy —
+# y ninguna otra.
+gv="$(runtime_stale_graph_version '{"detail":{"error":"graph_version_stale","message":"x","graph_version":88}}')" && rcx=0 || rcx=$?
+[ "$rcx" = 0 ] && [ "$gv" = 88 ] \
+  && echo "OK stale: detail.error anidado (forma real del hub)" \
+  || { echo "FAIL detail.error anidado (rc $rcx, gv '$gv')"; fail=1; }
+gv="$(runtime_stale_graph_version '{"reason":"stale_graph","graph_version":45}')" && rcx=0 || rcx=$?
+[ "$rcx" = 0 ] && [ "$gv" = 45 ] \
+  && echo "OK stale: reason en raiz (forma legacy)" \
+  || { echo "FAIL reason en raiz (rc $rcx, gv '$gv')"; fail=1; }
+gv="$(runtime_stale_graph_version '{"detail":{"error":"graph_version_stale"}}')" && rcx=0 || rcx=$?
+[ "$rcx" = 0 ] && [ -z "$gv" ] \
+  && echo "OK stale sin graph_version -> version vacia, sigue siendo stale" \
+  || { echo "FAIL stale sin version (rc $rcx, gv '$gv')"; fail=1; }
+runtime_stale_graph_version '{"detail":"el client_event_id ya identifica otro agregado"}' >/dev/null && rcx=0 || rcx=$?
+[ "$rcx" = 1 ] && echo "OK un 409 con detail string NO es grafo rancio" \
+  || { echo "FAIL detail string tratado como stale (rc $rcx)"; fail=1; }
+runtime_stale_graph_version '{"detail":{"error":"context_drift"}}' >/dev/null && rcx=0 || rcx=$?
+[ "$rcx" = 1 ] && echo "OK otro error anidado NO es grafo rancio" \
+  || { echo "FAIL otro error tratado como stale (rc $rcx)"; fail=1; }
+runtime_stale_graph_version 'esto no es json' >/dev/null && rcx=0 || rcx=$?
+[ "$rcx" = 1 ] && echo "OK respuesta ilegible NO es grafo rancio" \
+  || { echo "FAIL respuesta ilegible tratada como stale (rc $rcx)"; fail=1; }
+
+# 409 de grafo rancio en el carril directo: se anota el desfase y la petición SIGUE en la cola
+# (la refresca el heartbeat, #61), no se pierde ni se aparta a la primera. El cuerpo es el REAL
+# del hub — con la forma plana este bloque pasaba en verde contra un contrato inexistente.
 cat > "$TMP/routes-d.json" <<'JSON'
-{"POST /projects/p-1/epic-proposals": {"status": 409, "body": {"reason": "stale_graph", "graph_version": 60}},
+{"POST /projects/p-1/epic-proposals": {"status": 409, "body": {"detail": {"error": "graph_version_stale", "message": "el grafo avanzó", "graph_version": 60}}},
  "POST /events": {"status": 200, "body": {"accepted": [], "duplicates": [], "rejected": []}}}
 JSON
 runtime_graph_clear_stale
@@ -580,6 +624,8 @@ print(json.load(open('$rej12')).get('rejected_reason',''))" 2>/dev/null | grep -
   || echo "OK la razon del rechazo no inventa un desfase de grafo"
 
 # [Minor 6] "3 rechazos CONSECUTIVOS" es literal: un transitorio intercalado reinicia la racha.
+# Este bloque usa a propósito la forma PLANA (`reason: stale_graph`): es la compatibilidad hacia
+# atrás con una instancia anterior al contrato, y tiene que seguir entendiéndose.
 cat > "$TMP/routes-d.json" <<'JSON'
 {"POST /projects/p-1/epic-proposals": {"status": 409, "body": {"reason": "stale_graph", "graph_version": 70}},
  "POST /events": {"status": 200, "body": {"accepted": [], "duplicates": [], "rejected": []}}}