graph

Graph Skill

Ejecuta un grafo de orquestación determinista a partir de un descriptor JSON declarativo. El runtime consume los contratos sealed-descriptor y pure-scheduler en src/graph/* y se ejecuta mediante un proceso OS independiente (omc graph run), por lo que la recuperación ante fallos (matar a medio camino, reejecutar, reanudar desde el diario) funciona de verdad.

Uso

/oh-my-claudecode:graph <descriptor.json>
/oh-my-claudecode:graph "build then test then ask me before deploy"   (crear el descriptor primero)

La superficie de ejecución es siempre el subcomando CLI:

omc graph run <descriptor.json> [--runs-root <dir>]

Ejecútalo mediante la herramienta Bash para grafos no interactivos. Las líneas de progreso se muestran como [run], [node], [ok], [fail], [join], [done].

Cuándo Usarlo

• Pipelines multi-paso repetibles con dependencias explícitas (DAG)
• Trabajo que debe sobrevivir a interrupciones: matar/reiniciar reanuda desde el diario
• Ejecuciones auditables: diario OCC + instantáneas de proyección en .omc/graph-runs/<run_id>/

Cuándo NO usarlo: trabajo exploratorio de una sola vez (usar conversación o /team); cualquier cosa que necesite replanificación adaptativa a medio camino (los grafos son deterministas).

Flujo de Trabajo

1. Descriptor proporcionado -> ir al paso 3.

2. Pipeline descrito -> crear el descriptor JSON (esquema más abajo), escribirlo junto al proyecto (sugerir .omc/graphs/<nombre>.json) y mostrarlo al usuario antes de ejecutar. run_id debe ser único por pipeline lógico; reejecutar con el mismo run_id REANUDA, no reinicia.

3. Nodos de aprobación: si el descriptor contiene algún nodo "kind": "human-approval", NO lo ejecutes mediante la herramienta Bash (stdin no es interactivo allí; EOF falla cerrado a denegado). Indica al usuario que ejecute interactivamente:

   ! omc graph run <archivo>
   

   El prefijo ! lo ejecuta dentro de esta sesión con stdin en vivo para que funcione s/n.

4. Ejecutar y relatar el progreso. Códigos de salida (normativos): 0 éxito | 1 fallo terminal | 19 otro escritor posee esta ejecución (ocupado) 20 diario corrupto/manipulado (fallo cerrado) | 21 desviación del descriptor al reanudar | 70 fallo del runtime (error no mapeado)

5. Reanudar: reejecutar el mismo comando tras un fallo reproduce las transiciones confirmadas y continúa. Los nodos completados nunca se reejecutan.

Esquema del Descriptor (mínimo)

{
  "descriptor_version": 1,
  "run_id": "id-unico-del-pipeline",
  "revision_id": "rev-1",
  "goal": "una línea",
  "nodes": [
    { "id": "n1", "kind": "command", "title": "...", "timeout_ms": 60000,
      "max_attempts": 2, "effect_policy": { "policy": "side_effect_free" },
      "command": "npm test" },
    { "id": "a1", "kind": "agent", "title": "...", "timeout_ms": 300000,
      "max_attempts": 1, "effect_policy": { "policy": "side_effect_free" },
      "instructions": "..." },
    { "id": "gate", "kind": "human-approval", "title": "...",
      "prompt": "¿Proceder?" }
  ],
  "edges": [ { "id": "e1", "kind": "fixed", "from": "n1", "to": "a1" } ],
  "entry_node_ids": ["n1"],
  "concurrency_limit": 2,
  "terminal_verification_node_id": "a1"
}

Tipos de arista: fixed | conditional | fan_out/join pair | back_edge (reintentos acotados mediante max_traversals). Consulta src/graph/schema.ts para el esquema Zod autoritativo — y lee la sección de Límite de Capacidad anterior para ver qué ejecutores integrados ejecutan realmente hoy.

Límite de Capacidad y Semántica (leer antes de crear)

• Soporte de aristas: los ejecutores integrados de comando/agente cubren aristas fixed y pares fan_out/join. Las rutas conditional y back_edge son totalmente soportadas por el runtime y los contratos del scheduler, pero requieren un NodeExecutor personalizado que emita route en sus resultados — los ejecutores integrados nunca producen rutas, por lo que los grafos que dependen de ellas fallan rápidamente con route_required en lugar de adivinar.
• La garantía de recuperación ante fallos es al-menos-una-vez para nodos de comando: un fallo entre un efecto secundario externo y su apéndice en el diario reejecuta ese nodo al reanudar. Para comandos idempotent, la clave resuelta está disponible para el comando como GRAPH_IDEMPOTENCY_KEY antes de que comience y también se registra para deduplicación posterior. Los ejecutores integrados rechazan reconcile; la reconciliación requiere un ejecutor personalizado con una autoridad de reconciliación externa real. La ejecución exactamente-una-vez para efectos secundarios externos está fuera del alcance de v1.
• Límite de confianza del comando: los nodos de comando son líneas de shell arbitrarias con autoridad de proceso en el directorio de trabajo actual. Solo ejecuta descriptores que hayas escrito o en los que confíes. Los hijos del comando reciben un entorno permitido (PATH, HOME/USERPROFILE, TEMP/TMP, locale/timezone, identidad de USER, GRAPH_* y la clave de idempotencia opcional), no los secretos completos del host. Los comandos no están en un entorno aislado de archivos/sistema.
• Límite de autoridad del agente: los nodos de agente integrados son explícitamente de solo lectura. Se ejecutan en el directorio de trabajo actual sin directorios adicionales, solo Read, Glob y Grep, permissionMode: dontAsk, persistencia de sesión deshabilitada y una lista de entornos permitidos específica del proveedor. Los tiempos de espera del agente abortan e interrumpen la consulta del SDK. Usa un ejecutor personalizado para cualquier agente que necesite mutación o efectos externos. Trata .omc/graph-runs/<run_id>/descriptor.json como contenido ejecutable.