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:

• Identify which steps actually consume another step's output.
• Estimate independent width, critical path, scheduler overhead, and review

load. Require measurable payback or stronger independent evaluation.

• Keep one-shot or Loop execution when work is mainly sequential, small, or

cheaper to review serially.

• Limit V7.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>

• Write the JSON contract and run

scripts/validate_graph_contract.py <contract.json> --strict.

• Give every node one owner, typed inputs/outputs, explicit reads/writes,

verifier, timeout, attempt/tool caps, effect class, idempotency, and

compensation.

• Add only data, control, verification, failure, or compensation edges.

Schema-bearing edges must match both endpoint contracts.

• Enforce one writer per target. Agent workers use isolated artifacts or

worktrees; the integration owner controls shared schemas and final writes.

• 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.

• Schedule only READY nodes whose dependencies are verified. Persist every

transition and edge payload reference before releasing successors.

• Retry the failed node or smallest invalid subgraph after a changed

diagnosis. Preserve verified branches; never replay the whole graph merely

for convenience.

• 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.

• 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 V7.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>

Failure Protocol

• NEEDS_INPUT: a mandatory graph contract or authority field is unresolved.
• BLOCKED_DEPENDENCY: keep affected nodes WAITING; run only independent

ready nodes.

• BLOCKED_PERMISSION: deny the effect, preserve state, and request approval.
• VERIFY_FAILED: reject the node/join artifact and recover the smallest unit.
• NO_PROGRESS: the same failure repeats after a changed attempt.

max_attempts: 2 by default and always finite.

• BUDGET_STOP: stop scheduling, checkpoint, compensate active effects, and

return a partial graph receipt.

Output Contract

Return status, result (terminal decision and accepted artifacts), evidence

(validator, node, join, terminal, budget, approval, and cleanup receipts),

unknowns, and next_action (stop, retry node, compensate, approval, or

handoff).

Edge Cases

• Two workers both write report.md: strict validation fails the single-writer

invariant; isolate worker artifacts and let one reduce node own the report.

• A branch passes but its sibling times out: preserve the verified branch,

retry only the failed node within cap, and do not release the join until its

declared mode and verifier pass.

Success Metrics

• The strict graph validator passes before execution.
• Graph admission shows bounded value beyond orchestration and review cost.
• Every node, edge, join, effect, and terminal claim has fresh evidence.
• Recovery replays the smallest failed unit from durable state.

Quality Gates

• [ ] Static DAG scope and Loop/Teams/Harness boundaries are explicit.
• [ ] Owners, payload schemas, writers, joins, verifiers, and budgets are exact.
• [ ] State replay and duplicate delivery preserve graph invariants.
• [ ] External effects have independent review, approval, compensation, and rollback.
• [ ] Terminal verification supports the end-to-end claim.

</skill_contract>