ACOP

ACOP Compliance Profile v1.0

Status

Stability: stable. Version: acop-compliance/1.0. This profile 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 compliance profile. Adopting it is OPTIONAL: an ACOP core implementation that operates under no formal requirements is fully conformant without it. An implementation that declares support for acop-compliance/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 compliance-oriented extension profile for ACOP.

The goal is to let multi-agent code work operate under formalized requirements without forcing every ACOP deployment to become compliance-heavy.

The profile is built from four elements:

• formalized requirements
• a completeness matrix
• evidence-backed status
• explicit justifications for exceptions

Scope

The ACOP compliance profile extends ACOP core with:

• requirement catalogs
• control mappings
• completeness tracking
• evidence references
• exception / waiver justifications
• approval and policy gates

It does not replace ACOP core work-item semantics.

This profile should be treated as an extension layered on top of:

• acop.md
• acop.schema.json
• acop-compliance.schema.json
• acop_examples.md

It is not a separate orchestration protocol.

Core principle

Compliance MUST be machine-readable and reviewable.

That means:

• no hidden policy assumptions
• no vague “looks compliant” states
• every required control maps to evidence or an explicit exception

Extension concepts

Requirement

A formal requirement that applies to one or more coordinated work items.

Required fields:

• requirement_id
• name
• category
• description
• applies_to_work_kinds

Recommended fields:

• framework
• control_family
• severity
• owner_role
• required_evidence_kinds

Examples:

• code review required
• security scan required
• separation of duty required
• traceable validation evidence required
• architectural approval required

RequirementMatrixEntry

Represents one requirement applied to one work item or work scope.

Required fields:

• matrix_entry_id
• work_item_id
• requirement_id
• completeness_status

Recommended fields:

• evidence_ids
• exception_id
• assessed_at_utc
• assessed_by_agent_uid
• notes

CompletenessStatus

Recommended baseline enum:

• not_started
• partial
• satisfied
• blocked
• excepted
• not_applicable

Meaning:

• not_started: no evidence or exception yet
• partial: some evidence exists, but requirement is incomplete
• satisfied: evidence supports completion
• blocked: requirement cannot complete due to an unresolved blocker
• excepted: not satisfied normally, but an explicit approved exception exists
• not_applicable: requirement does not apply to this work item

EvidenceRecord

Represents evidence supporting a requirement or matrix entry.

Required fields:

• evidence_id
• evidence_kind
• summary
• created_at_utc

Recommended fields:

• artifact_ids
• resource_uri
• producer
• source_work_item_id
• validation_result
• review_result

Examples:

• test run result
• review artifact
• build output
• static analysis report
• approval note
• traceability report

ExceptionJustification

Represents a formal exception to a requirement: the record of a decision to accept a requirement as unmet.

Required fields:

• exception_id
• requirement_id
• scope
• justification
• approved_by_role

Recommended fields:

• exception_status (see § lifecycle)
• approved_by_agent_uid
• approved_at_utc
• risk_acceptance_summary
• mitigations
• expires_at_utc

An exception is the only sanctioned way for a requirement to go unmet. Two rules follow, and both are enforced in § Conformance:

• An exception against a requirement whose severity is high or critical MUST carry expires_at_utc. Permanent waivers on severe controls are how a compliance program decays into a formality.
• An exception against a requirement whose severity is high or critical MUST carry approved_by_agent_uid, binding the decision to an identity and not only to a symbolic role.

Neither rule is expressible in JSON Schema, because severity lives on the Requirement and the constraint applies to the ExceptionJustification that references it. Both are validated by conformance fixtures instead.

PolicyGate

Represents a gate that must pass before work may transition states.

Required fields:

• policy_gate_id
• name
• applies_to_transition
• gate_status

Recommended fields:

• blocking_requirement_ids
• required_approval_roles
• failure_summary

Example transitions:

• ready -> claimed
• in_progress -> completed
• completed -> consumed

Compliance matrix model

The central view of this profile is the compliance controls matrix.

At minimum it should answer:

• what requirements apply?
• what evidence exists?
• what is complete?
• what is still partial or blocked?
• what is excepted and why?

Recommended matrix columns:

• work_item_id
• requirement_id
• requirement_name
• category
• completeness_status
• evidence_count
• exception_id
• blocker_codes
• last_assessed_at_utc

Minimal lifecycle

1. apply requirements to work
2. collect evidence as work proceeds
3. update matrix completeness
4. record exceptions where necessary
5. enforce policy gates before key transitions
6. retain the matrix plus evidence chain as audit-friendly output

State machines

The state machines below are 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.

ExceptionJustification.exception_status

exception_status is an OPTIONAL field. Implementations that omit it MUST derive the status as follows, and MUST NOT treat an omitted status as approved:

• approved_at_utc absent → proposed
• approved_at_utc present, expires_at_utc absent or in the future → approved
• expires_at_utc in the past → expired

     +---------+
     | (start) |
     +----+----+
          |
          v
    +-----------+   (approver declines)   +-----------+
    | proposed  +------------------------>| rejected  |
    +-----+-----+                         +-----------+
          |
          | (required approver approves)
          v
    +-----------+   (expires_at_utc passes)   +-----------+
    | approved  +---------------------------->|  expired  |
    +-----+-----+                             +-----------+
          |
          | (withdrawn before expiry)
          v
    +-----------+
    |  revoked  |
    +-----------+

   Terminal escape (allowed from any non-terminal state):

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

Required transitions (MUST be supported):

From	To	Trigger
(start)	proposed	exception recorded, not yet approved
proposed	approved	an identity holding a required approval role approves
proposed	rejected	approver declines
approved	expired	expires_at_utc passes
approved	revoked	approver withdraws the exception before expiry
any non-terminal	superseded	replaced by a newer exception for the same requirement and scope

Forbidden transitions (MUST NOT be permitted):

• Any transition out of expired, revoked, rejected, or superseded. These are terminal. Renewing an exception requires a new ExceptionJustification, which supersedes the prior one — an expired exception MUST NOT be silently extended in place, because the extension would carry the original approval date and defeat the audit trail.
• proposed → expired. An unapproved exception never took effect.
• Any transition to approved recorded by an identity that does not hold a role in the requirement’s required_approval_roles, where the referenced policy gate declares them.

RequirementMatrixEntry.completeness_status

Only satisfied, not_applicable, and excepted are passing states. The critical rule binds excepted to a live exception:

An entry MUST NOT hold excepted unless it references an exception_id whose exception_status is approved. When the referenced exception reaches expired, revoked, rejected, or superseded, the implementation MUST transition the entry out of excepted — to blocked if no other evidence exists, or to the status its evidence supports.

An implementation that leaves an entry excepted behind a dead exception is non-conforming. This is the single most important rule in this profile: it is what stops a time-boxed waiver from quietly becoming permanent.

Required transitions (MUST be supported):

From	To	Trigger
(start)	not_started	requirement applied to a work item
(start)	not_applicable	requirement scoped out for this work item
not_started	partial	some but not all required evidence recorded
not_started	satisfied	all required evidence recorded at once
partial	satisfied	remaining required evidence recorded
partial	blocked	an unresolved blocker prevents completion
not_started	blocked	an unresolved blocker prevents starting
blocked	partial	blocker resolved, evidence still incomplete
blocked	satisfied	blocker resolved and evidence complete
not_started	excepted	an approved exception covers the requirement
partial	excepted	an approved exception covers the remainder
blocked	excepted	an approved exception covers the blocking gap
excepted	blocked	the covering exception is no longer approved
excepted	satisfied	evidence completed while the exception was in force
satisfied	partial	evidence invalidated, e.g. a superseded artifact

Forbidden transitions (MUST NOT be permitted):

• Any transition into excepted without a referenced exception in approved status.
• not_applicable → any other status without a new assessment recorded in assessed_at_utc and assessed_by_agent_uid. Scope changes MUST be attributable.
• satisfied → excepted. A satisfied requirement needs no waiver; requesting one indicates the evidence was withdrawn, which MUST be recorded as partial or blocked first.

PolicyGate.gate_status

A policy gate guards a core work-item transition named in applies_to_transition. An implementation MUST evaluate the gate before permitting that transition, and MUST refuse the transition unless the gate is passed or waived.

Required transitions (MUST be supported):

From	To	Trigger
(start)	pending	gate declared and not yet evaluated
pending	passed	every requirement in blocking_requirement_ids is in a passing state
pending	failed	at least one blocking requirement is not_started or partial
pending	blocked	at least one blocking requirement is blocked
pending	waived	an identity holding a role in required_approval_roles waives the gate
failed	passed	re-evaluation after the failing requirements reached a passing state
blocked	failed	blocker resolved, requirements still unmet
blocked	passed	blocker resolved and all requirements met
passed	failed	re-evaluation after evidence was invalidated

Forbidden transitions (MUST NOT be permitted):

• failed → waived or blocked → waived without an approval recorded by an identity holding a role in required_approval_roles. A waiver is an authorization decision, not a fallback for a failing gate.
• Any evaluation that reports passed while a blocking requirement is excepted under an exception that is not approved.
• Treating an unevaluated gate as passed. A gate that cannot be evaluated MUST report blocked, never passed.

Relationship to ACOP core

ACOP core remains responsible for:

• work identity
• blockers
• claims/leases
• artifacts
• validation hooks
• blackboard coordination

The compliance profile adds:

• formal requirement sets
• completeness accounting
• evidence obligations
• exception justifications
• gate enforcement semantics

Extension rule:

• ACOP compliance MUST reuse core ACOP identities and lifecycle semantics
• compliance-specific objects MUST attach to ACOP work items rather than redefining them
• future compliance schemas MUST be framed as profile/extension schemas over ACOP core, not as a disconnected sibling protocol

The initial machine-readable compliance profile now lives at:

• acop-compliance.schema.json

Blackboard and compliance

Blackboard entries can contribute to compliance, but they are not compliance truth on their own.

Examples:

• a blackboard finding may inform a risk requirement
• a blackboard decision may point to an approval artifact
• a blackboard partial_result may contribute evidence

But compliance state should still live in:

• requirement matrix entries
• evidence records
• exception justifications
• policy gates

This keeps informal collaboration and formal compliance from collapsing into one object.

Design rules

• Every requirement in a matrix MUST resolve to evidence, an explicit blocker, or an approved exception. “No entry” is not a passing state.
• Exceptions MUST carry a justification and MUST NOT be treated as equivalent to satisfaction in any report or gate evaluation.
• Compliance state SHOULD be queryable and reviewable by both humans and agents.
• This profile MUST remain transport-neutral and compatible with A2A/MCP layering; it defines documents, not a transport.

Producer alignment

A producer should eventually be able to emit ACOP-compliance-compatible evidence for:

• validation plans and results
• review artifacts
• blocker codes
• structured justifications for deferred or exceptional paths

A producer should not become the compliance authority by itself.

Resolved design decisions

These were open in v0.1 and are settled for v1.0.

Requirement catalogs are workspace-local. A requirement_id MUST be unique and stable within a workspace; it carries no global meaning. A requirement that originates in an external control catalog SHOULD name that catalog in framework and its control in control_family. Globally versioned catalogs are OPTIONAL and out of scope for this profile — mandating them would force every deployment to adopt a registry it may not need, and the framework field already carries the provenance that makes an external mapping auditable.

Approval roles are symbolic, with identity binding required where it matters. approved_by_role is a symbolic role name and MUST NOT be assumed to resolve to a directory entry. For exceptions against high or critical requirements, approved_by_agent_uid MUST also be present, so severe waivers are attributable to an identity rather than to a role that anyone might claim. Requiring identity binding everywhere was rejected: it would block adoption in deployments whose reviewers are not enrolled as agents, and low-severity waivers do not carry the risk that justifies it.

Exception expiration is mandatory for severe requirements. expires_at_utc MUST be present on exceptions against high or critical requirements, and is OPTIONAL otherwise. An expired exception MUST NOT be extended in place; renewal creates a new exception that supersedes it. See § exception_status.

Conformance

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

1. Validate every persisted or emitted compliance document against acop-compliance.schema.json.
2. Carry compliance_profile_version equal to acop-compliance/1.0 in every compliance document, and reject documents whose profile version it does not accept.
3. Honor the three state machines in § State machines. Forbidden transitions MUST be rejected.
4. Refuse to hold a matrix entry in excepted when its referenced exception is not in approved status, transitioning the entry out of excepted when the exception expires, is revoked, is rejected, or is superseded.
5. Reject an exception against a high or critical requirement that lacks expires_at_utc or approved_by_agent_uid.
6. Refuse a core work-item transition named in a policy gate’s applies_to_transition unless that gate is passed or waived.
7. Report blocked, never passed, for a gate it cannot evaluate.
8. Resolve every requirement_id, exception_id, and evidence_id reference to a declared object. Dangling references MUST be rejected.
9. Treat blackboard entries as informational: a blackboard entry MUST NOT by itself move a matrix entry to satisfied.

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

Conformance with this profile does not imply conformance with acop-orchestration.md, and neither implies the other. An orchestration gate whose release_policy is all_required_compliance_satisfied requires both.

This site is open source. Improve this page.