Graph (Graph-Skill)

Graph-Skill

Führe einen deterministischen Orchestrierungsgraphen aus einem deklarativen JSON-Descriptor aus. Die Laufzeit nutzt die Contracts sealed-descriptor und pure-scheduler in src/graph/* und führt die Ausführung als unabhängigen OS-Prozess (omc graph run) aus, sodass eine Crash-Wiederherstellung (Abbruch mitten im Lauf, erneutes Ausführen, Fortsetzen über Journal) wirklich funktioniert.

Verwendung

/oh-my-claudecode:graph <descriptor.json>
/oh-my-claudecode:graph "build then test then ask me before deploy"   (zuerst den Descriptor erstellen)

Die Ausführung erfolgt immer über den CLI-Subbefehl:

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

Führe ihn über das Bash-Tool für nicht-interaktive Graphen aus. Fortschrittszeilen werden als [run], [node], [ok], [fail], [join], [done] ausgegeben.

Wann verwenden

• Wiederholbare Multi-Step-Pipelines mit expliziten Abhängigkeiten (DAG)
• Arbeiten, die Unterbrechungen überstehen müssen: Kill/Neustart setzt über das Journal fort
• Auditierbare Läufe: OCC-Journal + Projektions-Snapshots unter .omc/graph-runs/<run_id>/

NICHT verwenden für: explorative Einmalarbeiten (nutze Konversation oder /team); alles, was adaptive Neuplanung während des Laufs erfordert (Graphen sind deterministisch).

Arbeitsablauf

1. Descriptor gegeben -> gehe zu Schritt 3.

2. Pipeline beschrieben -> erstelle den Descriptor (JSON, Schema unten), schreibe ihn neben das Projekt (Vorschlag: .omc/graphs/<name>.json) und zeige ihn dem Benutzer vor der Ausführung. run_id muss pro logischer Pipeline eindeutig sein; ein erneuter Lauf mit derselben run_id SETZT FORT, startet nicht neu.

3. Genehmigungsknoten: Wenn der Descriptor einen Knoten vom Typ "kind": "human-approval" enthält, führe ihn NICHT über das Bash-Tool aus (stdin ist dort nicht interaktiv; EOF schlägt mit Verweigerung fehl). Sage dem Benutzer stattdessen, er solle interaktiv ausführen:

   ! omc graph run <Datei>
   

   Das !-Präfix führt den Befehl innerhalb dieser Sitzung mit live stdin aus, sodass j/n funktioniert.

4. Ausführen und Fortschritt melden. Exit-Codes (normativ): 0 erfolgreich | 1 endgültig fehlgeschlagen | 19 ein anderer Schreiber besitzt diesen Lauf (belegt) 20 korruptes/manipuliertes Journal (Fail-Closed) | 21 Descriptordrift bei Wiederaufnahme | 70 Laufzeitabsturz (nicht zugeordneter Fehler)

5. Wiederaufnahme: Ein erneuter Befehl nach einem Absturz spielt festgeschriebene Übergänge ab und fährt fort. Abgeschlossene Knoten werden nie erneut ausgeführt.

Descriptor-Schema (minimal)

{
  "descriptor_version": 1,
  "run_id": "unique-pipeline-id",
  "revision_id": "rev-1",
  "goal": "one line",
  "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": "Weiter?" }
  ],
  "edges": [ { "id": "e1", "kind": "fixed", "from": "n1", "to": "a1" } ],
  "entry_node_ids": ["n1"],
  "concurrency_limit": 2,
  "terminal_verification_node_id": "a1"
}

Arten von Kanten: fixed | conditional | fan_out/join-Paare | back_edge (begrenzte Wiederholungen über max_traversals). Siehe src/graph/schema.ts für das maßgebliche Zod-Schema – und lies den Abschnitt Capability Boundary oben, um zu verstehen, welche integrierten Executors heute tatsächlich ausgeführt werden.

Capability-Grenze & Semantik (vor dem Erstellen lesen)

• Kantenunterstützung: Die integrierten Executors für Befehle/Agenten unterstützen fixed-Kanten und fan_out/join-Paare. conditional- und back_edge-Routen werden vollständig von der Laufzeit und den Scheduler-Contracts unterstützt, erfordern jedoch einen benutzerdefinierten NodeExecutor, der auf seinen Ergebnissen eine route ausgibt – integrierte Executors erzeugen niemals Routen, sodass Graphen, die darauf angewiesen sind, schnell mit route_required fehlschlagen, anstatt zu raten.
• Crash-Wiederherstellungsgarantie ist mindestens einmal für Befehlsknoten: Ein Absturz zwischen einem externen Seiteneffekt und seinem Journal-Anhang führt bei der Wiederaufnahme zur erneuten Ausführung dieses Knotens. Für idempotente Befehle ist der aufgelöste Schlüssel dem Befehl als GRAPH_IDEMPOTENCY_KEY vor seinem Start verfügbar und wird auch für nachgelagerte Deduplizierung aufgezeichnet. Integrierte Executors lehnen reconcile ab; Abgleich erfordert einen benutzerdefinierten Executor mit einer tatsächlichen externen Abgleichsinstanz. Exakt-einmal für externe Seiteneffekte liegt außerhalb des Rahmens von v1.
• Befehlsvertrauensgrenze: Befehlsknoten sind beliebige Shell-Zeilen mit Prozessberechtigungen im aktuellen Arbeitsverzeichnis. Führe nur Descriptoren aus, die du selbst geschrieben hast oder denen du vertraust. Befehlskinder erhalten eine zugelassene Umgebung (PATH, HOME/USERPROFILE, TEMP/TMP, Gebietsschema/Zeitzone, USER-Identität, GRAPH_* und den optionalen Idempotenzschlüssel), nicht die vollständigen Geheimnisse des Hosts. Befehle sind nicht in Dateisystem/Prozess-Sandboxen isoliert.
• Agentenautoritätsgrenze: Integrierte Agentenknoten sind explizit schreibgeschützt. Sie laufen im aktuellen Arbeitsverzeichnis ohne zusätzliche Verzeichnisse, nur mit Read, Glob und Grep, permissionMode: dontAsk, Sitzungspersistenz deaktiviert und einer anbieterspezifischen Umgebungs-Zulassungsliste. Agenten-Timeouts brechen ab und unterbrechen die SDK-Abfrage. Verwende einen benutzerdefinierten Executor für jeden Agenten, der Mutationen oder externe Effekte benötigt. Behandle .omc/graph-runs/<run_id>/descriptor.json als ausführbaren Inhalt.