orchestrate-delivery-graph

name

orchestrate-delivery-graph

description

Automate a Manifest-bound delivery across Positioning, PRD, Spec, Impact, Plan, Test Plan, implementation, verification, and Candidate review by coordinating independent author/reviewer loops inside a human-approved Authority Envelope. Use when a user asks to execute a feature end to end, reduce repeated document confirmations, automate workflow gates, use graph engineering for delivery, or continue automatically while escalating only scope choices, authority expansion, non-convergence, and irreversible actions.

Orchestrate Delivery Graph

Run the configured delivery graph without asking the human to inspect routine artifact revisions. Separate artifact quality from human authority: use an independent reviewer for quality and interrupt the human only at exception or irreversible-action boundaries.

Establish Authority

1. Read AGENTS.md, the active Manifest, config/workflow-policy.json, and config/delivery-graph.json.
2. Classify the task before changing files.
3. Persist or identify one human-approved Authority Envelope containing the goal, non-goals, exact targets, allowed change kinds, human-required change kinds, and authorized actions.
4. Treat absent authority as denied. Never infer approval from a draft, saved plan, actor name, or prior artifact.
5. Ask once for missing material choices. Do not ask for routine formatting, traceability, clarification, or testability corrections.

Each artifact state must name the exact non-empty project-relative targets being reviewed. Keep them within the Envelope allowlist; never infer them from the working tree or artifact prose.

Read review-protocol.md before creating review records or launching an independent reviewer.

Execute a Node

For the current graph node:

1. Invoke the node's authoring or implementation Skill.
2. Run deterministic repository checks before agent review.
3. Assign a reviewer whose canonical actor identity differs from the artifact author. Reject surrounding whitespace and compare identities case-insensitively. Give the reviewer the artifact, upstream artifacts, Authority Envelope, and required contract; do not give it the desired verdict or prior diagnosis.
4. Require one structured PASS, REVISE, ESCALATE, or BLOCKED verdict.
5. Run scripts/validate_artifact_bundle.py with the envelope, state, and verdict records.
6. Follow only the returned decision:
   • ADVANCE: enter next_node without human confirmation.
   • REVISE: apply only routine findings, update the digest, and request a new independent review.
   • ESCALATE: stop and ask the human for the exact named decision.
   • BLOCKED: preserve evidence and report the blocking condition.
   • COMPLETE: report completion.

Preserve the returned current node, input verdict, and input-record digests as the audit binding for that decision. Do not reuse a decision with changed inputs.

Do not invoke artifact review for a human-authority-required node. The reducer also verifies that the Envelope authorizes the current action and will return E_AUTHORITY if a caller attempts to skip into an unauthorized node.

Do not let the author reduce or approve its own verdict. Do not replace an unavailable independent reviewer with self-review; escalate instead.

Preserve Convergence

Keep finding IDs stable until resolved. Preserve every rejected revision and review record. On REVISE, verify that the artifact digest changes and stay within the configured revision budget. Convert reviewer disagreement into the configured reviewer-conflict change kind.

Return upstream when a downstream artifact exposes a routine traceability defect. Escalate instead when the repair changes a goal, non-goal, target boundary, Tier, budget, dependency, data access, security posture, or architecture choice.

Respect Irreversible Boundaries

Treat artifact-review PASS as permission to enter the next reversible node, not as mutation authority. Keep the existing Candidate and independent Technical Review flow. Stop for separate authority before commit, push, merge, deployment, release, or external messages, even if those actions appear in an earlier plan.

Validate a Bundle

Run:

python3 skills/orchestrate-delivery-graph/scripts/validate_artifact_bundle.py \
  --envelope <authority-envelope.json> \
  --state <artifact-state.json> \
  --verdict <review-verdict.json> \
  --format json

Exit 0 means ADVANCE or COMPLETE; exit 1 means a valid REVISE, ESCALATE, or BLOCKED decision; exit 2 means invalid evidence or configuration. Never bypass a nonzero result.