Graph Engineering

Graph Engineering

<skill_contract> <input>A dependency-heavy objective with candidate nodes, data schemas, owners, effects, verifiers, joins, budgets, and durable state paths.</input> <output>A validated static DAG contract with typed edges, explicit joins, node-local recovery, and graph-level receipts.</output> <done>Static invariants and terminal acceptance checks pass with fresh node, join, budget, permission, and state evidence.</done> <non_goals>Temporal loop design, worker-team command, runtime-kernel implementation, dynamic graphs, or universal parallelism.</non_goals>

Use Graph Engineering for dependency width. Use loop-engineering for repeated execution through time, agent-teams-command for process ownership and IPC, and harness-engineering for scheduler, permission, lease, and observability infrastructure. A graph node may contain a bounded Loop or Agent Team.

Usage Template

Provide: objective/non-goals, candidate nodes, real data dependencies, payload schemas, owners and write territories, join semantics, node/terminal verifiers, effects and permissions, artifact/state paths, budgets, stop conditions, and recovery. Load references/graph-contract.md for the full schema and boundary; start from references/diamond-graph-example.json.

Workflow

<intake>

Run the admission gate before drawing a graph:

1. Identify which steps actually consume another step's output.
2. Estimate independent width, critical path, scheduler overhead, and review load. Require measurable payback or stronger independent evaluation.
3. Keep one-shot or Loop execution when work is mainly sequential, small, or cheaper to review serially.
4. Limit V8.1 to a static DAG: sequence, pipeline, diamond, maker-checker, or bounded subgraph. Put repetition inside a loop node; reject graph cycles and dynamic expansion.

</intake>

<unknowns_gate>

Return NEEDS_INPUT when objective, graph owner, dependency direction, payload schema, writer, verifier, permission boundary, budget, join, or recovery is missing and cannot be discovered safely. Probe candidate independence with a small dry run. Do not invent an edge merely because two steps are adjacent.

</unknowns_gate>

<execute>

1. Write the JSON contract and run scripts/validate_graph_contract.py <contract.json> --strict.
2. Give every node one owner, typed inputs/outputs, explicit reads/writes, verifier, timeout, attempt/tool caps, effect class, idempotency, and compensation.
3. Add only data, control, verification, failure, or compensation edges. Schema-bearing edges must match both endpoint contracts.
4. Enforce one writer per target. Agent workers use isolated artifacts or worktrees; the integration owner controls shared schemas and final writes.
5. Declare a join for every multi-input node. Choose all, reduce, first-success, quorum, barrier-verifier, or human-gate; name the exact input set and verifier.
6. Schedule only READY nodes whose dependencies are verified. Persist every transition and edge payload reference before releasing successors.
7. Retry the failed node or smallest invalid subgraph after a changed diagnosis. Preserve verified branches; never replay the whole graph merely for convenience.
8. Require human approval, a compensation route, and verified rollback before any external, shared, destructive, published, credentialed, or financial effect. In strict contracts, name the external node ID in approval_required, feed it a typed approval receipt directly from a human-gate, and list each exact write target as allowed and not denied.
9. At terminal nodes, verify the end-to-end objective and graph guardrails; node success alone cannot certify graph success.

</execute>

<evaluate>

Check static integrity: known endpoints, compatible schemas, reachability, acyclicity, single writers, complete joins, finite budgets, and compensated effects. Check runtime integrity: deterministic readiness, duplicate-delivery idempotency, checkpoint replay, permission denial without mutation, smallest-unit recovery, terminal evidence, and cleanup. Use an independent reviewer for consequential graph behavior.

</evaluate>

<retry_policy>

max_attempts comes from each node and never exceeds the graph cap. Retry only after changing diagnosis, input, owner, tool, or strategy. Stop on a repeated signature, incompatible edge, permission denial, invalid checkpoint, exhausted review budget, or NO_PROGRESS. Whole-graph retry is forbidden in strict V8.1.

</retry_policy>

<state_contract>

Persist {run_id, graph_id, status, attempt, budget, evidence, unknowns, last_error, next_action} plus contract/implementation hashes, node states, edge payload locators, join decisions, writer leases, approvals, checkpoints, compensations, terminal receipts, and cleanup. Use append-only events and an atomic current checkpoint; chat history is not graph state.

</state_contract>