@trycore/spec-build-harness 0.12.0 → 0.13.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "trycore-spec-build-harness",
   "displayName": "Trycore — Spec & Build Harness",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Arnés de construcción de dos loops (slice por épica + release gate) para Claude Code, con gates de calidad, estado compartido y OpenSpec. Compañero de @trycore/spec-product-flow. Agnóstico al proyecto.",
   "author": {
     "name": "Trycore",

package/VERSION

@@ -1 +1 @@
-0.12.0
+0.13.0

package/commands/build/onboard.md

@@ -243,30 +243,47 @@ en el runtime. **Importarlo es un acto de gobierno**: la superficie exige sesió
 el token de agente. El arnés **prepara y valida**; una persona sube.
 
 1. Extrae el grafo de los artefactos de discovery ya leídos (`docs/03-backlog/epicas.md`,
-   `docs/02-user-story-map/`, `docs/04-historias/`) a un JSON:
+   `docs/02-user-story-map/`, `docs/04-historias/`) a un JSON. **Las dependencias las extrae
+   el script, no tú** (paso 2): puebla `depends_on` con lo que veas, pero **nunca lo dejes
+   vacío por defecto** — un grafo sin aristas no falla, solo empobrece el Lienzo en silencio
+   (issue #56: 41/41 épicas llegaron al hub con `depends_on: []`).
 
    ```json
    {"project_ref": "<nombre del proyecto>",
     "epics": [{"code": "EP-001", "title": "…", "layer": "foundational",
                "files_scope": ["src/core/**"], "depends_on": [],
-               "stories": [{"id": "HU-001", "title": "…"}]}],
-    "release_lines": [{"id": "R1-mvp", "epics": ["EP-001"]}]}
+               "stories": [{"id": "HU-001", "title": "…"}]},
+              {"code": "EP-002", "title": "…", "layer": "business",
+               "files_scope": ["src/pagos/**"], "depends_on": ["EP-001"],
+               "stories": [{"id": "HU-011", "title": "…"}]}],
+    "release_lines": [{"id": "R1-mvp", "epics": ["EP-001", "EP-002"]}]}
    ```
 
-2. Normalízalo y valídalo (determinista, nunca sube nada). La salida va a
-   `.claude/state/graph-bundle.json` para que `trycore-build migrate` la encuentre sola:
+2. Normalízalo y valídalo (determinista, nunca sube nada). **Pasa siempre `--from-docs`**: el
+   script relee el campo `**Depende de**` de cada sección de épica y **une** ese grafo al del
+   JSON — es la única lectura fiable de las dependencias, que la metodología escribe como
+   prosa. La salida va a `.claude/state/graph-bundle.json` para que `trycore-build migrate` la
+   encuentre sola:
 
    ```bash
-   python3 .claude/scripts/lib/graph-bundle.py < /tmp/epics.json > .claude/state/graph-bundle.json
+   python3 .claude/scripts/lib/graph-bundle.py --from-docs docs/03-backlog/epicas.md \
+     < /tmp/epics.json > .claude/state/graph-bundle.json
    ```
 
+   Para inspeccionar solo lo extraído (sin armar el bundle):
+   `python3 .claude/scripts/lib/graph-bundle.py --print-deps docs/03-backlog/epicas.md`.
+   Si una épica declara el campo estructurado `depende_de: [EP-001]`, ese gana sobre la prosa.
+
    El script emite las épicas en el **formato exacto del hub**: `layer` en MAYÚSCULA
    (`FOUNDATIONAL`|`BUSINESS` — un layer inválido rechaza el grafo ENTERO), historias con
    `code`, y `release_line` (string) por épica.
 
 3. **Lee los avisos** (`warnings` del bundle y stderr): capa ausente, dependencia inexistente,
-   ciclo, línea de release que referencia una épica desconocida. Corrígelos en discovery — el arnés
-   **no inventa** el grafo ni edita `epicas.md` (salvo el carve-out de la épica caparazón, Fase 2c).
+   ciclo, línea de release que referencia una épica desconocida, épica que está en los docs pero
+   no en tu JSON, épica sin campo `Depende de`. Contrasta la línea `info: … N aristas en el
+   grafo` con lo que declara el backlog: **0 aristas en un backlog con dependencias es el
+   síntoma de #56**. Corrígelos en discovery — el arnés **no inventa** el grafo ni edita
+   `epicas.md` (salvo el carve-out de la épica caparazón, Fase 2c).
 
 4. **Entrega al ADMIN un solo fichero.** Si vas a migrar historial, corre `trycore-build migrate`:
    embebe el grafo como sección `graph` del bundle de estado (un único fichero para la pantalla de

package/dist/lib/normalize.js

@@ -1118,6 +1118,17 @@ export function verifyNormalizedBundle(bundle) {
                 message: 'source_key debe tener entre 1 y 200 caracteres (LegacyImported, event_catalog.py:446)',
             });
         }
+        // ImportBundleIn tipa `original` como dict: un escalar responde 422
+        // `dict_type` en la validación pydantic y tumba el bundle ENTERO, antes de
+        // la persistencia por-entrada (issue #55). El bundle sale envuelto de
+        // `wireOriginal`; esto es la red que lo detecta en seco si alguien vuelve a
+        // emitir un escalar por otra vía.
+        if (typeof u.original !== 'object' || u.original === null || Array.isArray(u.original)) {
+            violations.push({
+                source_key: `unmapped[${i}]`,
+                message: 'original debe ser un objeto JSON: el hub lo tipa como dict y responde 422 dict_type sobre el bundle entero (ImportBundleIn)',
+            });
+        }
     });
     return violations;
 }

package/dist/lib/state-bundle.js

@@ -72,6 +72,20 @@ export function graphEpicsWithoutRepresentation(graph, representedCodes) {
         .map((e) => (typeof e.code === 'string' ? e.code : ''))
         .filter((code) => code !== '' && !represented.has(code));
 }
+/** El hub tipa `unmapped[].original` como dict (`ImportBundleIn`): un escalar
+ * responde 422 `dict_type` y tumba el bundle ENTERO en la validación pydantic,
+ * antes de la persistencia por-entrada — observado en el piloto con
+ * `facts[project_kind_source]: "auto"` (issue #55), pero lo emiten cuatro
+ * sitios (fact fuera de catálogo, elemento de history[] no-objeto, nota de
+ * release y `parallel_front.status: "closed"`). Los normalizadores conservan
+ * el valor legacy tal cual — la envoltura pertenece al cable y solo alcanza a
+ * lo que no es ya un objeto JSON, para no anidar dos veces lo que ya viaja bien. */
+function wireOriginal(entry) {
+    const { original } = entry;
+    if (typeof original === 'object' && original !== null && !Array.isArray(original))
+        return entry;
+    return { ...entry, original: { value: original } };
+}
 export function buildStateBundle(raw, projectRef, preHarness) {
     const warnings = [];
     const st = typeof raw === 'object' && raw !== null && !Array.isArray(raw) ? raw : {};
@@ -94,7 +108,7 @@ export function buildStateBundle(raw, projectRef, preHarness) {
     const fronts = front ? [front] : [];
     const factsUnmapped = [];
     const facts = normalizeFacts(st, EPOCH_ISO, warnings, factsUnmapped);
-    const unmapped = [...historyUnmapped, ...releasesUnmapped, ...frontUnmapped, ...factsUnmapped];
+    const unmapped = [...historyUnmapped, ...releasesUnmapped, ...frontUnmapped, ...factsUnmapped].map(wireOriginal);
     // Épicas pre-arnés (issue #42): lista CONFIRMADA por el humano — entrada
     // sintética archivada sin gates por épica (patrón del workaround del piloto).
     // Conflicto obvio ⇒ error, no fusión: una épica declarada pre-arnés que YA

package/docs/runtime/protocolo-cliente-runtime.md

@@ -201,3 +201,29 @@ reducer **no bloquea** el trabajo local: se avisa y queda como discrepancia del
 **Lo que el agente NO hace** (superficies humanas, con PDP): cerrar una release, planificar/abrir/
 drenar/cerrar un front, subir el bundle de import del grafo y publicar contexto. El arnés prepara,
 propone y reporta; la persona decide en la consola del hub.
+
+---
+
+## 11. Bundle de import histórico (`POST /projects/{id}/import/bundle`)
+
+Lo produce `trycore-build migrate` (`src/lib/state-bundle.ts`) y lo sube una persona con sesión de
+ADMIN. La validación del hub es **pydantic sobre el cuerpo entero**: un solo campo mal tipado
+responde 422 y rechaza el bundle completo **antes** de la persistencia por-entrada — no hay
+degradación parcial. De ahí que el contrato de las secciones "de rescate" importe tanto como el de
+los eventos.
+
+`unmapped[]` — todo lo que el estado legacy trae y el catálogo del hub no sabe nombrar (spec §7:
+*nada se pierde, nada bloquea*):
+
+| Campo | Tipo exigido | Nota |
+|---|---|---|
+| `source_key` | string, 1..200 | `LegacyImported`, `event_catalog.py:446` |
+| `original` | **dict** | un escalar responde 422 `dict_type` (issue #55) |
+| `occurred_at` | ISO-8601 UTC | ancla del dato legacy, no la hora de la migración |
+
+El estado legacy guarda escalares en cuatro de los sitios que caen aquí (fact fuera de catálogo,
+elemento de `history[]` no-objeto, nota de release, `parallel_front.status: "closed"`), así que
+`buildStateBundle` **envuelve** todo `original` que no sea ya un objeto JSON como `{"value": …}`.
+La envoltura es del cable: los normalizadores conservan el valor legacy tal cual, y un `original`
+que ya es dict viaja intacto (nunca se anida dos veces). `migrate --verify` comprueba el invariante
+en seco, sin red.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trycore/spec-build-harness",
-  "version": "0.12.0",
+  "version": "0.13.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/graph-bundle.py

@@ -14,8 +14,17 @@ como string POR ÉPICA (las `release_lines` de la entrada se pliegan aquí). As
 objeto sirve para la pantalla de import del grafo y para embeberse como sección `graph`
 del bundle de estado (`trycore-build migrate`).
 
+[issue #56] Las dependencias entre épicas viven como PROSA en `docs/03-backlog/epicas.md`
+(`**Depende de**: EP-001 (…)`), y delegar su lectura al modelo las dejó VACÍAS en el piloto
+(41/41 épicas con `depends_on: []`, Lienzo sin una sola arista). `--from-docs` extrae ese
+grafo de forma DETERMINISTA — regex de códigos `EP-…` sobre el campo `Depende de` de cada
+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.
+
 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
 
 Entrada (stdin, JSON — formato de discovery, sin cambios):
     {"project_ref": "…",
@@ -27,9 +36,12 @@ Salida (stdout, JSON): el bundle normalizado y DETERMINISTA (orden estable por c
 los problemas no bloquean: se listan como avisos en stderr y en `warnings` del bundle, con
 el criterio del arnés — nada se pierde en silencio, nada bloquea la preparación.
 
-Códigos de salida: 0 = bundle generado (con o sin avisos) · 1 = entrada ilegible.
+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).
 """
 import json
+import re
 import sys
 import datetime
 
@@ -43,8 +55,128 @@ def norm_list(v):
     return [x for x in v if isinstance(x, str)] if isinstance(v, list) else []
 
 
+# ── Extractor determinista de dependencias desde los docs de discovery [issue #56] ──
+# Códigos de épica: EP-001 y también los compuestos del estilo EP-OR-08.
+RE_CODIGO = re.compile(r"\bEP-(?:[A-Za-z]{1,6}-)?\d{1,4}\b")
+# Encabezado de sección de épica: `## EP-001 — Título` (cualquier nivel).
+RE_ENCABEZADO = re.compile(r"^\s{0,3}(#{1,6})\s+(.*)$")
+# El campo en prosa que escribe la metodología: `**Depende de**: …` (puede ir a mitad de
+# línea, p. ej. `**Anexo A**: Fase 3 · **Depende de**: EP-002`).
+RE_DEPENDE_DE = re.compile(r"depende\s+de", re.IGNORECASE)
+# El campo estructurado (frontmatter o cuerpo): `depende_de: [EP-001, EP-002]`.
+RE_DEPENDE_DE_ESTRUCTURADO = re.compile(r"^\s*(?:-\s*)?depende_de\s*:", re.IGNORECASE)
+# Fin del párrafo del campo: encabezado, regla horizontal, viñeta/cita/tabla o campo nuevo.
+RE_FIN_DE_CAMPO = re.compile(r"^\s*(?:#{1,6}\s|-{3,}\s*$|\*{3,}\s*$|[-*+>|]\s|\*\*)")
+
+
+def extraer_dependencias(texto):
+    """Devuelve ({codigo: [deps ordenadas]}, {códigos con sección}, avisos).
+
+    Solo entran las épicas que DECLARAN el campo (en prosa o estructurado): "no lo declara"
+    y "declara que no depende de nada" son cosas distintas y ninguna se inventa aquí.
+    """
+    avisos = []
+    lineas = texto.splitlines()
+    # (código de la épica, línea donde abre su sección)
+    secciones = []
+    for i, linea in enumerate(lineas):
+        m = RE_ENCABEZADO.match(linea)
+        if not m:
+            continue
+        codigos = RE_CODIGO.findall(m.group(2))
+        if codigos:
+            secciones.append((codigos[0], i))
+    if not secciones:
+        avisos.append("no se reconoció ninguna sección de épica en los docs "
+                      "(se esperaban encabezados del estilo `## EP-001 — Título`)")
+        return {}, set(), avisos
+
+    deps = {}
+    for n, (codigo, inicio) in enumerate(secciones):
+        fin = secciones[n + 1][1] if n + 1 < len(secciones) else len(lineas)
+        cuerpo = lineas[inicio + 1:fin]
+        prosa, estructurado = None, None
+        for j, linea in enumerate(cuerpo):
+            if estructurado is None and RE_DEPENDE_DE_ESTRUCTURADO.match(linea):
+                estructurado = RE_CODIGO.findall(linea.split(":", 1)[1])
+                continue
+            if prosa is not None:
+                continue
+            m = RE_DEPENDE_DE.search(linea)
+            if not m:
+                continue
+            # El campo puede continuar en las líneas siguientes hasta el fin del párrafo.
+            trozos = [linea[m.end():]]
+            for siguiente in cuerpo[j + 1:]:
+                if not siguiente.strip() or RE_FIN_DE_CAMPO.match(siguiente):
+                    break
+                trozos.append(siguiente)
+            prosa = RE_CODIGO.findall(" ".join(trozos))
+        # El campo estructurado es determinista: gana sobre la heurística de la prosa.
+        encontrado = estructurado if estructurado is not None else prosa
+        if encontrado is None:
+            continue
+        deps[codigo] = sorted({c for c in encontrado if c != codigo})
+    return deps, {c for c, _ in secciones}, avisos
+
+
+def leer_dependencias_de_docs(ruta):
+    """Lee el fichero de épicas; lanza IOError/OSError si no se puede (rc 1 arriba)."""
+    with open(ruta, encoding="utf-8") as fh:
+        return extraer_dependencias(fh.read())
+
+
+def parsear_argumentos(argv):
+    """({from_docs, print_deps}, error) — sin dependencias, mismo estilo que el resto."""
+    opciones = {"from_docs": None, "print_deps": None}
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        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
+            opciones["from_docs" if arg == "--from-docs" else "print_deps"] = argv[i + 1]
+            i += 2
+            continue
+        return opciones, "opción desconocida: %s" % arg
+    if opciones["from_docs"] and opciones["print_deps"]:
+        # Ignorar una de las dos en silencio es exactamente el error que corrige #56.
+        return opciones, "--from-docs y --print-deps son excluyentes"
+    return opciones, None
+
+
 def main():
     avisos = []
+    opciones, error = parsear_argumentos(sys.argv[1:])
+    if error:
+        print("graph-bundle: %s" % error, file=sys.stderr)
+        return 1
+
+    # `--print-deps`: solo el grafo extraído (diagnóstico; no toca stdin ni arma bundle).
+    if opciones["print_deps"]:
+        try:
+            deps, _, avisos_docs = leer_dependencias_de_docs(opciones["print_deps"])
+        except (IOError, OSError) as e:
+            print("graph-bundle: no se pudo leer %s: %s" % (opciones["print_deps"], e),
+                  file=sys.stderr)
+            return 1
+        json.dump(deps, sys.stdout, indent=2, ensure_ascii=False, sort_keys=True)
+        sys.stdout.write("\n")
+        for a in avisos_docs:
+            print("aviso: %s" % a, file=sys.stderr)
+        return 0
+
+    deps_docs = None
+    if opciones["from_docs"]:
+        try:
+            deps_docs, secciones_docs, avisos_docs = \
+                leer_dependencias_de_docs(opciones["from_docs"])
+        except (IOError, OSError) as e:
+            print("graph-bundle: no se pudo leer %s: %s" % (opciones["from_docs"], e),
+                  file=sys.stderr)
+            return 1
+        avisos.extend(avisos_docs)
+
     try:
         raw = json.load(sys.stdin)
     except Exception as e:
@@ -113,6 +245,36 @@ def main():
             epica["docs_ref"] = e["docs_ref"]
         epicas[code] = epica
 
+    # [issue #56] Las dependencias de los docs se UNEN a las declaradas: el extractor es la
+    # fuente fiable, y lo que ya venía en el JSON no se pierde (se avisa si no está en docs).
+    if deps_docs is not None:
+        aristas = 0
+        for code, e in epicas.items():
+            if code not in deps_docs:
+                if code in secciones_docs:
+                    avisos.append("%s tiene sección en %s pero no declara el campo "
+                                  "`Depende de`: sus dependencias quedan como vinieran en el "
+                                  "JSON" % (code, opciones["from_docs"]))
+                else:
+                    avisos.append("%s no aparece como sección de épica en %s: sus "
+                                  "dependencias no se pudieron extraer de los docs"
+                                  % (code, opciones["from_docs"]))
+                continue
+            solo_json = [d for d in e["depends_on"] if d not in deps_docs[code]]
+            if solo_json:
+                avisos.append("%s: %s viene del JSON de entrada pero no del campo `Depende de` "
+                              "de los docs: verifica cuál manda"
+                              % (code, ", ".join(solo_json)))
+            e["depends_on"] = sorted(set(e["depends_on"]) | set(deps_docs[code]))
+            aristas += len(e["depends_on"])
+        for code in sorted(deps_docs):
+            if code not in epicas:
+                avisos.append("%s está en %s pero no en el JSON de entrada: el grafo del hub "
+                              "quedaría sin esa épica" % (code, opciones["from_docs"]))
+        print("info: dependencias extraídas de %s -> %d épicas con campo `Depende de`, "
+              "%d aristas en el grafo" % (opciones["from_docs"], len(deps_docs), aristas),
+              file=sys.stderr)
+
     for code, e in epicas.items():
         for dep in e["depends_on"]:
             if dep not in epicas:
@@ -167,6 +329,8 @@ def main():
         "generated_at": datetime.datetime.now(datetime.timezone.utc)
                         .strftime("%Y-%m-%dT%H:%M:%SZ"),
         "generated_by": "trycore-build-harness/graph-bundle.py",
+        "depends_on_source": ("docs:%s" % opciones["from_docs"]) if deps_docs is not None
+                             else "input",
         "epics": [epicas[c] for c in sorted(epicas)],
         "warnings": avisos,
     }

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

@@ -1593,4 +1593,122 @@ 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; }
+
+
 exit $fail