ACOP

ACOP Orchestration Extension v1.0

Status

Stability: stable. Version: acop-orchestration/1.0. This extension is versioned independently from ACOP core; it follows the same additive-versus- breaking rules as core. See acop.md § Versioning policy.

This document is normative for the orchestration extension. Adopting it is OPTIONAL: an ACOP core implementation that does not orchestrate staged work is fully conformant without it. An implementation that declares support for acop-orchestration/1.0 MUST satisfy § Conformance.

Conventions

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals. Lowercase appearances of these words carry their ordinary English meaning and are not normative.

Purpose

This document defines a reusable orchestration extension for ACOP.

Core ACOP defines work coordination semantics:

The orchestration extension adds a higher-order execution flow that can be loaded by a lead agent or orchestration middleware and used to control multi-agent development work across phases, lanes, gates, and acceptance transitions.

This is intended for projects that need stronger flow control than “here is a queue of work items,” especially when:

The schema is intentionally project-agnostic: it describes flow structure, not any particular delivery methodology.

Relationship to ACOP core

The orchestration extension is layered on top of:

It does not replace ACOP core work items.

Instead:

Why this exists

In complex multi-agent development, the missing contract is often not “what a work item looks like” but “what order and gate structure should govern those work items.”

Examples:

These are orchestration semantics, not just work-item semantics.

Core concepts

OrchestrationFlow

The top-level reusable execution definition.

Required fields:

Recommended fields:

Stage

A major bounded segment of work.

Examples:

Required fields:

Lane

A parallelizable stream of work within a stage.

Examples:

Required fields:

Gate

A stop/check/release checkpoint.

Required fields:

Examples:

ReleaseCondition

Declares what must become true before a stage, lane, or gate can release downstream work.

Examples:

AcceptanceRecord

Represents accepted completion of a unit in the orchestration flow.

This is especially important for graph-backed orchestration because acceptance state should be queryable independently from raw work-item completion.

Examples:

FlowEdge

Declares the orchestration dependency graph.

Examples:

Execution semantics

1. Flow first

An implementation MUST load the orchestration flow before creating or claiming work governed by that flow. A work item that declares a governing flow unit whose flow is not loaded MUST NOT be treated as actionable.

2. Release, do not just enqueue

This is the central guarantee of the extension. A downstream ACOP work item governed by a release condition MUST NOT be presented as actionable — that is, MUST NOT enter ready — until that release condition is satisfied as defined in § Release evaluation.

An implementation that enqueues downstream work and relies on workers to refrain from claiming it does NOT conform. The restriction MUST be enforced by the coordination owner, because a worker cannot be assumed to be cooperative.

3. Acceptance is stronger than completion

A work item reaching core status completed MUST NOT by itself satisfy a release condition. Orchestration progress is carried by AcceptanceRecord objects, whose lifecycle is defined in § AcceptanceRecord.acceptance_status.

This separation is deliberate: completed is a worker’s assertion about its own output, while accepted is a decision made by the party that owns the gate. Collapsing the two lets a worker release its own downstream work.

4. Gates are explicit ownership boundaries

Every Gate SHOULD declare an owner_role. A gate whose release_policy is explicit_owner_approval MUST declare an owner_role, and an implementation MUST reject an acceptance record targeting such a gate unless the recording identity holds that role.

5. Blackboard and compliance extend the flow

Blackboard entries and ACOP compliance records MAY be linked to stages, lanes, gates, and acceptance records. Such links are informational: a blackboard entry MUST NOT satisfy a release condition on its own. Where a gate’s release_policy is all_required_compliance_satisfied, the authority is the compliance extension’s requirement matrix, not the blackboard. See acop-compliance.md.

Release evaluation

A release condition is evaluated against its release_policy. An implementation MUST evaluate the policies below as specified, and MUST treat a condition as unsatisfied whenever the required state cannot be determined. “Fail open” is non-conforming: an undeterminable gate MUST block.

release_policy Satisfied when
all_upstream_accepted Every target named in required_gate_ids, required_lane_ids, and required_stage_ids has a current acceptance status of accepted or released.
all_required_artifacts_present Every artifact in the gate’s required_artifact_ids is present and resolvable.
all_required_validation_passed Every validation in the gate’s required_validation_ids has passed.
all_required_compliance_satisfied Every requirement in the gate’s required_requirement_ids has a matrix entry whose completeness_status is satisfied, not_applicable, or excepted under a currently approved exception.
explicit_owner_approval An acceptance record with status accepted exists for the gate, recorded by an identity holding the gate’s owner_role.
custom Implementation-defined. An implementation MUST document its evaluation rule and MUST NOT treat custom as automatically satisfied.

A release condition naming no targets and no required artifacts, validations, or requirements is vacuous. An implementation MUST reject such a condition at load time rather than treating it as satisfied — a gate that silently permits everything is the failure this extension exists to prevent.

State machines

The state machine below is normative. A conforming implementation MUST implement every transition labeled MUST, MAY implement every transition labeled MAY, and MUST NOT permit any transition that is neither.

AcceptanceRecord.acceptance_status

Gates, lanes, and stages do not carry a status field of their own. The current status of a flow unit is the acceptance_status of the most recently recorded non-superseded AcceptanceRecord whose target_id names that unit. A unit with no acceptance record is pending. Implementations MUST NOT introduce a parallel status field on the unit itself; two sources of truth for release state is precisely how downstream work escapes its gate.

                      +---------+
                      | (start) |
                      +----+----+
                           |
                           v
                     +-----------+
                     |  pending  |
                     +-----+-----+
                           |
             (underlying work completes)
                           |
                           v
              +-------------------------+
        +---->| completed_not_accepted  |<----+
        |     +-----------+-------------+     |
        |                 |                   |
        |          (reviewer examines)        | (rework submitted)
        |                 v                   |
        |           +-----------+             |
        |           | reviewed  +-------------+
        |           +-----+-----+   (rejected)
        |                 |               |
        |                 | (owner        v
        |                 |  accepts) +-----------+
        |                 |           | rejected  |
        |                 v           +-----+-----+
        |           +-----------+           |
        +-----------+ accepted  |           |
        (rejected    +-----+-----+           |
         after                |              |
         acceptance)   (release conditions   |
                        satisfied)           |
                              v              |
                        +-----------+        |
                        | released  |        |
                        +-----------+        |
                                             |
   Terminal escape (allowed from any non-terminal state, including rejected):

     any non-terminal  --(replaced by a newer record)-->  superseded

Required transitions (MUST be supported):

From To Trigger
(start) pending acceptance record created for a flow unit
pending completed_not_accepted underlying work reaches core status completed
completed_not_accepted reviewed reviewer examines the unit
reviewed accepted gate owner accepts
reviewed rejected reviewer or owner rejects
accepted released release conditions satisfied; downstream released
rejected completed_not_accepted rework submitted for re-review
any non-terminal superseded replaced by a newer acceptance record

Optional transitions (MAY be supported):

From To Trigger
completed_not_accepted accepted flows with no distinct review step; acceptance is the review
completed_not_accepted rejected rejected before review, e.g. missing required artifacts
accepted rejected acceptance withdrawn before release

Forbidden transitions (MUST NOT be permitted):

Conformance

An implementation that declares support for acop-orchestration/1.0 MUST:

  1. Validate every persisted or emitted orchestration document against acop-orchestration.schema.json.
  2. Carry orchestration_profile_version equal to acop-orchestration/1.0 in every orchestration document, and reject documents whose profile version it does not accept.
  3. Honor the acceptance_status state machine. Forbidden transitions MUST be rejected.
  4. Withhold ready from any work item whose governing release condition is unsatisfied, enforced by the coordination owner rather than by worker cooperation.
  5. Evaluate every release_policy as specified in § Release evaluation, treating undeterminable state as unsatisfied.
  6. Reject vacuous release conditions at flow load time.
  7. Resolve every from_id and to_id in flow_edges, and every target_id in release conditions and acceptance records, to a declared flow unit. Dangling references MUST be rejected at load time.
  8. Derive flow-unit status solely from acceptance records, without a parallel status field.

Implementations SHOULD execute the orchestration conformance fixtures in fixtures/ as part of their CI.

Conformance with this extension does not imply conformance with acop-compliance.md. A gate whose release_policy is all_required_compliance_satisfied requires both.

graph-friendly projection

This extension is designed to project cleanly into the graph projection layer.

Recommended node types:

Recommended edges:

Projection is OPTIONAL — an implementation that does not project into a graph is still conformant. An implementation that does project MUST relay acceptance status, since the graph is otherwise unable to answer the questions the projection exists for:

Example use

A staged delivery program can express:

The same schema applies to:

Worked documents are in acop_examples.md.

Files

This site is open source. Improve this page.