@trycore/spec-build-harness 0.14.2 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trycore/spec-build-harness",
-  "version": "0.14.2",
+  "version": "0.16.0",
   "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/lib/front-plan.py

@@ -5,9 +5,19 @@
 (conjunto disjunto + merge_order) que un humano aprueba al abrir el front en la consola del
 hub. No llama al runtime ni lee el estado: entra JSON por stdin, sale JSON por stdout.
 
-stdin: JSON [{"epica","layer","files_scope":[glob]}]
+stdin: JSON [{"epica","layer","files_scope":[glob],"depends_on":[EP-XXX]}]
 stdout: {"selected":[...],"serialized":[{"epica","reason"}],"excluded_foundational":[...]}
 Determinista: orden por 'epica'. Solape de globs por prefijo de directorio o glob idéntico.
+
+Las tres compuertas, en orden (METODOLOGIA §5 «Compuertas del front»):
+  G1  `layer` fundacional  -> excluded_foundational (nunca en paralelo).
+  G2a `files_scope` vacío o ausente -> serialized. «Sin `files_scope` declarado, una épica no
+      es candidata al front» (METODOLOGIA:343): fail-CLOSED. Que dos épicas sin ámbito
+      declarado salieran «disjuntas» era exactamente el fallo que el front no puede permitirse.
+  G2b camino en el DAG de `depends_on` con una épica ya seleccionada -> serialized. Dos épicas
+      encadenadas no son paralelizables aunque sus ficheros no se toquen: la de abajo construye
+      sobre lo que la de arriba todavía no ha mergeado.
+  G2c solape de `files_scope` con una épica ya seleccionada -> serialized.
 """
 import json, sys, fnmatch
 
@@ -24,6 +34,37 @@ def overlap(a, b):
                 return True
     return False
 
+def is_foundational(cand):
+    """G1 normalizada. El bundle del grafo emite `layer` en MAYÚSCULA (graph-bundle.py lo
+    `.upper()`a porque el hub lo exige así) mientras METODOLOGIA lo escribe en minúscula: un
+    `== "foundational"` a secas dejaba pasar `FOUNDATIONAL` al front, en silencio y justo en la
+    compuerta que más caro sale saltarse."""
+    layer = cand.get("layer")
+    return isinstance(layer, str) and layer.strip().lower() == "foundational"
+
+def reachability(cands):
+    """Alcance transitivo de `depends_on` entre las candidatas (clausura por Floyd-Warshall
+    booleano; los conjuntos de épicas de un front son de decenas, no de miles).
+
+    Se calcula sobre TODAS las candidatas, fundacionales incluidas: un camino EP-A → EP-F → EP-B
+    encadena A y B aunque la fundacional del medio no entre al front. Las referencias a épicas
+    que no vienen en la entrada se ignoran — aquí no se inventa un grafo que no se ha visto."""
+    codes = [c.get("epica") for c in cands if isinstance(c.get("epica"), str)]
+    known = set(codes)
+    reach = {c: set() for c in codes}
+    for c in cands:
+        code = c.get("epica")
+        if code not in known:
+            continue
+        for dep in c.get("depends_on") or []:
+            if isinstance(dep, str) and dep in known and dep != code:
+                reach[code].add(dep)
+    for k in codes:
+        for i in codes:
+            if k in reach[i]:
+                reach[i] |= reach[k]
+    return reach
+
 def _empty_result():
     return {"selected": [], "serialized": [], "excluded_foundational": []}
 
@@ -33,15 +74,23 @@ def main():
         if not isinstance(cands, list) or not all(isinstance(c, dict) for c in cands):
             raise ValueError("entrada inválida: se esperaba una lista de objetos")
         cands = sorted(cands, key=lambda c: c.get("epica",""))
-        excluded = [c["epica"] for c in cands if c.get("layer") == "foundational"]
-        pool = [c for c in cands if c.get("layer") != "foundational"]
+        reach = reachability(cands)
+        excluded = [c["epica"] for c in cands if is_foundational(c)]
+        pool = [c for c in cands if not is_foundational(c)]
         selected, sel_scopes, serialized = [], [], []
         for c in pool:
+            code = c["epica"]
             sc = c.get("files_scope") or []
-            if any(overlap(sc, s) for s in sel_scopes):
-                serialized.append({"epica": c["epica"], "reason": "solape de files_scope con épica seleccionada"})
+            if not sc:
+                serialized.append({"epica": code,
+                                   "reason": "sin files_scope declarado: no es candidata al front (METODOLOGIA §5 G2)"})
+            elif any(code in reach.get(s, ()) or s in reach.get(code, ()) for s in selected):
+                serialized.append({"epica": code,
+                                   "reason": "dependencia en el grafo con una épica ya seleccionada"})
+            elif any(overlap(sc, s) for s in sel_scopes):
+                serialized.append({"epica": code, "reason": "solape de files_scope con épica seleccionada"})
             else:
-                selected.append(c["epica"]); sel_scopes.append(sc)
+                selected.append(code); sel_scopes.append(sc)
         print(json.dumps({"selected":selected,"serialized":serialized,"excluded_foundational":excluded}))
     except Exception:
         print(json.dumps(_empty_result()))

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/smoke-test.sh

@@ -5,7 +5,7 @@ DIR="$(cd "$(dirname "$0")" && pwd)"
 FAILED=0
 
 echo "── Tests del motor de contexto y front ──"
-for t in test-schema.sh test-config.sh test-runtime-client.sh test-hooks-runtime.sh test-skill-ops.sh test-reconciler.sh test-context-monitor.sh test-front-plan.sh test-install.sh; do
+for t in test-schema.sh test-config.sh test-runtime-client.sh test-hooks-runtime.sh test-skill-ops.sh test-worktree-identity.sh test-reconciler.sh test-context-monitor.sh test-front-plan.sh test-install.sh; do
   if bash "$DIR/tests/$t"; then echo "smoke: $t OK"; else echo "smoke: $t FALLÓ"; FAILED=1; fi
 done
 

package/scripts/tests/test-config.sh

@@ -63,4 +63,44 @@ 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; }
 
+# ── [#74] Señal de identidad heredada ─────────────────────────────────────────
+# El fallback de arriba es correcto para LEER y veneno para ESCRIBIR: sin una señal
+# que lo distinga, un worktree sin credenciales propias firma sus actos con la
+# identidad del clon principal y nadie se entera. Estos tres helpers son esa señal.
+
+got="$(cd "$WT" && CLAUDE_PROJECT_DIR="$WT" config_candidate_root)"
+WTP="$(cd "$WT" && pwd -P)"
+[ "$got" = "$WTP" ] && echo "OK config_candidate_root devuelve ESTE árbol, sin fallback" \
+  || { echo "FAIL config_candidate_root ($got, esperado $WTP)"; fail=1; }
+
+got="$(cd "$WT" && CLAUDE_PROJECT_DIR="$WT" config_main_clone_root)"
+[ "$got" = "$MAIN" ] && echo "OK config_main_clone_root ve el clon principal desde el worktree" \
+  || { echo "FAIL config_main_clone_root ($got, esperado $MAIN)"; fail=1; }
+
+(cd "$WT" && CLAUDE_PROJECT_DIR="$WT" config_is_inherited_root) \
+  && echo "OK config_is_inherited_root detecta el worktree sin credenciales propias" \
+  || { echo "FAIL config_is_inherited_root no detecta la herencia"; fail=1; }
+
+# El clon principal NUNCA hereda: es el dueño del estado.
+(cd "$MAIN" && CLAUDE_PROJECT_DIR="$MAIN" config_is_inherited_root) \
+  && { echo "FAIL config_is_inherited_root marca herencia en el clon principal"; fail=1; } \
+  || echo "OK config_is_inherited_root no marca al clon principal"
+
+# Un proyecto sin arnés tampoco: no hay identidad que heredar.
+(cd "$BARE" && CLAUDE_PROJECT_DIR="$BARE" config_is_inherited_root) \
+  && { echo "FAIL config_is_inherited_root marca herencia sin estado en ninguna parte"; fail=1; } \
+  || echo "OK config_is_inherited_root no marca un proyecto sin arnés"
+
+# Y en cuanto el worktree tiene credenciales PROPIAS, deja de heredar — sin tocar nada
+# más: es exactamente lo que `slice-ops.sh register` deja hecho.
+mkdir -p "$WT/.claude/state"
+echo '{"runtime_url":"http://localhost","agent_key":"ak-wt"}' > "$WT/.claude/state/runtime.credentials"
+(cd "$WT" && CLAUDE_PROJECT_DIR="$WT" config_is_inherited_root) \
+  && { echo "FAIL sigue heredando con credenciales propias"; fail=1; } \
+  || echo "OK con credenciales propias el worktree deja de heredar"
+got="$(cd "$WT" && CLAUDE_PROJECT_DIR="$WT" config_root)"
+[ "$got" = "$WT" ] && echo "OK config_root ancla en el worktree ya registrado" \
+  || { echo "FAIL config_root tras registrar ($got, esperado $WT)"; fail=1; }
+rm -f "$WT/.claude/state/runtime.credentials"
+
 exit $fail

package/scripts/tests/test-front-plan.sh

@@ -25,6 +25,59 @@ echo "$out" | python3 -c "import json,sys;d=json.load(sys.stdin);
 assert d['selected']==['EP-010'] and [m['epica'] for m in d['serialized']]==['EP-011'], d
 print('OK front-plan mid-wildcard overlap serializado')" || { echo "FAIL mid-wildcard overlap"; fail=1; }
 
+# ── [#74] G1 normalizada: el bundle del grafo emite `layer` en MAYÚSCULA ─────────────
+# graph-bundle.py hace `.upper()` porque el hub lo exige así; front-plan comparaba contra
+# "foundational" en minúscula. La exclusión G1 no disparaba, en silencio, justo en la
+# compuerta que más caro sale saltarse.
+out="$(run '[{"epica":"EP-001","layer":"FOUNDATIONAL","files_scope":["src/**"]},
+             {"epica":"EP-002","layer":"BUSINESS","files_scope":["src/a/**"]}]')"
+echo "$out" | python3 -c "import json,sys;d=json.load(sys.stdin);
+assert d['excluded_foundational']==['EP-001'], d
+assert d['selected']==['EP-002'], d
+print('OK front-plan G1 con layer en MAYÚSCULA')" || { echo "FAIL G1 mayúscula"; fail=1; }
+
+# ── [#74] G2 fail-CLOSED sin files_scope ─────────────────────────────────────────────
+# METODOLOGIA:343: «sin `files_scope` declarado, una épica no es candidata al front». El
+# código hacía lo contrario: con la lista vacía, `overlap([], …)` es falso y dos épicas sin
+# ámbito salían como disjuntas.
+out="$(run '[{"epica":"EP-020","layer":"business","files_scope":[]},
+             {"epica":"EP-021","layer":"business"},
+             {"epica":"EP-022","layer":"business","files_scope":["src/c/**"]}]')"
+echo "$out" | python3 -c "import json,sys;d=json.load(sys.stdin);
+assert d['selected']==['EP-022'], d
+assert {m['epica'] for m in d['serialized']}=={'EP-020','EP-021'}, d
+assert all('files_scope' in m['reason'] for m in d['serialized']), d
+print('OK front-plan sin files_scope -> serialized (fail-closed)')" || { echo "FAIL fail-closed sin files_scope"; fail=1; }
+
+# ── [#74] G2 por camino en el DAG de `depends_on` ────────────────────────────────────
+# Ficheros disjuntos no bastan: si EP-031 depende de EP-030, la de abajo construye sobre lo
+# que la de arriba todavía no ha mergeado. La transitividad cuenta, y el camino vale aunque
+# pase por una fundacional que no entra al front.
+out="$(run '[{"epica":"EP-030","layer":"business","files_scope":["src/x/**"]},
+             {"epica":"EP-031","layer":"business","files_scope":["src/y/**"],"depends_on":["EP-030"]},
+             {"epica":"EP-032","layer":"business","files_scope":["src/z/**"],"depends_on":["EP-031"]},
+             {"epica":"EP-033","layer":"business","files_scope":["src/w/**"],"depends_on":["EP-099"]}]')"
+echo "$out" | python3 -c "import json,sys;d=json.load(sys.stdin);
+assert d['selected']==['EP-030','EP-033'], d
+assert {m['epica'] for m in d['serialized']}=={'EP-031','EP-032'}, d
+assert all('grafo' in m['reason'] for m in d['serialized']), d
+print('OK front-plan serializa el camino transitivo del DAG')" || { echo "FAIL DAG depends_on"; fail=1; }
+
+out="$(run '[{"epica":"EP-040","layer":"business","files_scope":["src/x/**"]},
+             {"epica":"EP-041","layer":"FOUNDATIONAL","files_scope":["src/f/**"],"depends_on":["EP-040"]},
+             {"epica":"EP-042","layer":"business","files_scope":["src/z/**"],"depends_on":["EP-041"]}]')"
+echo "$out" | python3 -c "import json,sys;d=json.load(sys.stdin);
+assert d['selected']==['EP-040'], d
+assert [m['epica'] for m in d['serialized']]==['EP-042'], d
+print('OK front-plan ve el camino que pasa por una fundacional excluida')" || { echo "FAIL DAG a través de fundacional"; fail=1; }
+
+# Sin `depends_on` declarado nada cambia: el campo es opcional, no se inventa un grafo.
+out="$(run '[{"epica":"EP-050","layer":"business","files_scope":["src/p/**"]},
+             {"epica":"EP-051","layer":"business","files_scope":["src/q/**"]}]')"
+echo "$out" | python3 -c "import json,sys;d=json.load(sys.stdin);
+assert d['selected']==['EP-050','EP-051'] and d['serialized']==[], d
+print('OK front-plan sin depends_on no serializa de más')" || { echo "FAIL sin depends_on"; fail=1; }
+
 SK="$ROOT/skills/managing-parallel-front/SKILL.md"
 { [ -f "$SK" ] && grep -q 'git worktree add' "$SK" && grep -q 'front-plan.py' "$SK" \
   && grep -q 'merge_order' "$SK" && grep -q 'foundational' "$SK"; } \
@@ -35,4 +88,14 @@ SK="$ROOT/skills/managing-parallel-front/SKILL.md"
 grep -q 'files_scope' "$ROOT/skills/building-a-slice/references/dor.md" && echo "OK dor files_scope" || { echo "FAIL dor files_scope"; fail=1; }
 grep -q 'parallel_front' "$ROOT/agents/build/build-orchestrator.md" && echo "OK orquestador front" || { echo "FAIL orquestador front"; fail=1; }
 
+# [#74] La skill decía «mismo token de proyecto»: el hub lo refuta (el `agent_key` es el
+# `agent_id` grabado en el token por el ADMIN). Un token repetido = un solo agente.
+grep -q 'mismo token de proyecto' "$SK" \
+  && { echo "FAIL la skill sigue diciendo «mismo token de proyecto»"; fail=1; } \
+  || echo "OK la skill ya no manda reusar el token de proyecto"
+grep -q 'slice-ops.sh register' "$SK" && echo "OK la skill manda dar de alta el worktree con register" \
+  || { echo "FAIL la skill no menciona register"; fail=1; }
+grep -q 'depends_on' "$SK" && echo "OK la skill pide depends_on entre las candidatas" \
+  || { echo "FAIL la skill no pide depends_on"; fail=1; }
+
 exit $fail

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": []}}}