Protocol v7

The protocol is the product. It defines how agents collaborate under human governance: how turns are structured, how decisions are recorded, how phases advance through gates, and how humans retain final authority. v7 is the current constitution.

Need the current normative boundary instead of the overview? See Protocol Reference v7. Building a non-CLI runner? See Runner Interface.

Overview

Protocol v7 elevates four v6 extensions to constitutional conformance surfaces: delegation chains, cross-run decision carryover, parallel turns, and run event lifecycle. These capabilities were implemented and shipped during v6 but were not verified by the conformance fixture corpus until v7.

v6 closed the constitutional gap left by v5 with the coordinator initiative (multi-repo), enforced challenge for review_only roles, structured verification evidence, and the decision ledger. v7 builds on that foundation with hierarchical authority (delegation), governance continuity (repo-durable decisions), concurrent execution (parallel turns), and structured observability (event lifecycle).

Version history

Version	Release	Key changes
v4	2025-Q1	Initial governed mode. Single-repo only. Phases and roles. Manual adapter. No structured decisions or objections.
v5	2025-Q3	Added local_cli and api_proxy adapters. Introduced decision/objection schema. Added verification evidence. Plugin system (script hooks). Dashboard.
v6	2026-Q1	Coordinator initiative (multi-repo). super_run_id linking. Cross-repo barriers and gates. HTTP hooks. review_only objection enforcement. Decision ledger as constitutional record. Mixed artifact schemas: governed config 1.0, governed state 1.1, coordinator config/state 0.1.
v7	2026-Q2	Delegation chains with decision contracts. Cross-run decision carryover (durability: "repo"). Parallel turns (max_concurrent_turns). Run event lifecycle (events.jsonl). 108 conformance fixtures across 13 surfaces.

Repo-local governed run

A governed run within a single repository is the foundation of the protocol. Every concept in v7 builds on this base.

Files

Path	Purpose
agentxchain.json	Project configuration: roles, adapters, phases, plugin config
.agentxchain/state.json	Mutable run state: current phase, pending turn, blocked status, run ID
.agentxchain/history.jsonl	Append-only log of all accepted turn results (one JSON object per line)
.agentxchain/decision-ledger.jsonl	Append-only ledger for accepted decisions plus selected conflict/governance events
.agentxchain/events.jsonl	Append-only run lifecycle events (run_started, turn_dispatched, turn_accepted, blocking/escalation, run_completed)
.agentxchain/run-history.jsonl	Terminal run summaries for the current run, with inherited continuity kept under separate parent metadata
.agentxchain/dispatch/turns/<turn_id>/	Dispatch bundle for each turn (ASSIGNMENT.json, PROMPT.md, CONTEXT.md)
.agentxchain/staging/<turn_id>/turn-result.json	Staged turn result awaiting acceptance
.agentxchain/prompts/<role>.md	Role prompt templates
.planning/	Human-facing planning artifacts (PM_SIGNOFF.md, ROADMAP.md, etc.)
TALK.md	Free-form communication channel between human and agents

Commands

The governed run is driven by a sequence of commands:

init → step (pm) → approve-transition
     → step (dev)
     → step (qa) → approve-completion

Each step creates a turn, validates the staged result, and normally auto-accepts it into history. Configured acceptance policies can still block or escalate before commit. accept-turn exists for recovery flows (interrupted turns, pre-staged results, or policy-blocked turns that need a retry). Gates (approve-transition, approve-completion) are human-approval checkpoints that the orchestrator cannot bypass.

Phase model

Phase	Purpose	Entry gate	Exit gate
planning	PM defines scope, acceptance criteria, roadmap	init (automatic)	approve-transition to implementation
implementation	Dev writes code, tests, documentation	approve-transition from planning	implementation_complete (requires verification pass, no human approval)
qa	QA challenges the implementation, verifies evidence, and issues the ship verdict	approve-transition from implementation	approve-completion

Custom phases can be defined in agentxchain.json. The table above describes the shipped default scaffold, not a hardcoded protocol limit.

Gate request lifecycle

Repo-local gates have a two-stage lifecycle in the shipped runtime:

1. An accepted turn may request a phase transition or run completion while other active turns still exist. In that case the request is retained as queued_phase_transition or queued_run_completion.
2. When the active turn set drains, AgentXchain evaluates the queued request. If the structural gate passes without human approval, the phase advances or the run completes immediately.
3. If the gate requires human approval, the run pauses and materializes pending_phase_transition or pending_run_completion.
4. agentxchain approve-transition and agentxchain approve-completion resolve those pending gates after explicit human sign-off.

This queued-versus-pending distinction matters in parallel mode. A request can be accepted into history before it becomes an approvable pending gate.

Challenge requirement

Mandatory challenge is a protocol rule, but the concrete non-empty objections requirement is scoped to review_only roles. The runtime validates that review_only turns raise at least one objection. Authoritative and proposed-write roles are still expected to challenge prior work, but they are not rejected solely for omitting objections.

Decision durability and overrides

Decision carryover in v7 is explicit rather than implicit:

• durability: "run" is the default decision scope and does not escape the current run.
• durability: "repo" promotes a decision into repo-level continuity so continuation runs still inherit it.
• overrides: "DEC-..." is how one accepted repo decision replaces another. The fixture-backed v7 rules prove a valid override targets an existing active repo decision, and self-override is invalid.

Coordinator initiative

The coordinator initiative extends governed runs across multiple repositories. A coordinator manages a super_run_id that links repo-level runs through workstreams, barriers, and cross-repo gates.

Core concepts

Concept	Description
super_run_id	Initiative-wide run identifier linking child repo runs
Workstream	Ordered cross-repo delivery slice with a declared phase, repo set, entry repo, and barrier type
Barrier	Cross-repo coordination state tracked in .agentxchain/multirepo/barriers.json
Cross-repo gate	Human approval at the coordinator level, approved with agentxchain multi approve-gate
Coordinator hooks	Super-run hooks: before_assignment, after_acceptance, before_gate, on_escalation

Shipped contract

The current coordinator surface is repo-native and local-first:

• Config file: agentxchain-multi.json
• Coordinator state root: .agentxchain/multirepo/
• Dispatch context artifacts: COORDINATOR_CONTEXT.json and COORDINATOR_CONTEXT.md
• Recovery rule: repo-local .agentxchain/ state is authoritative; coordinator state is derived and can be rebuilt from repo truth

Operator loop

1. agentxchain multi init loads agentxchain-multi.json and links or initializes child governed runs.
2. agentxchain multi step detects divergence, auto-resyncs when safe, then dispatches the next repo-local assignment.
3. The selected child repo completes its normal governed turn lifecycle.
4. A later agentxchain multi step projects the accepted child result, updates barriers, and either dispatches again or requests a gate.
5. If the coordinator blocks, the operator fixes the cause and runs agentxchain multi resume to restore active or paused.
6. agentxchain multi approve-gate clears pending coordinator phase or completion gates.

See Multi-Repo Coordination for the actual config schema, barrier types, hook phases, context files, dashboard views, and recovery flow. This protocol page stays at the constitutional layer; the deep-dive page carries the implementation-facing operator contract.

Compatibility

v7 extends v6 — it does not replace it. A v5 single-repo governed run remains valid under the current contract through the v6 compatibility path, and the coordinator initiative remains opt-in. v7 adds four constitutional surfaces on top of that base: delegation chains, cross-run decision carryover, parallel turns, and run event lifecycle.

Feature	v5	v6	v7
Single-repo governed runs	Yes	Yes	Yes
Decisions and objections	Yes	Yes (review_only turns must raise objections)	Yes
Verification evidence	Yes	Yes	Yes
Script plugin hooks	Yes	Yes	Yes
HTTP plugin hooks	No	Yes	Yes
Dashboard	Yes	Yes	Yes
super_run_id linking	No	Yes	Yes
Cross-repo barriers	No	Yes	Yes
Coordinator initiative	No	Yes	Yes
Cross-repo context generation	No	Yes	Yes
Coordinator hooks	No	Yes	Yes
Decision ledger as constitutional record	Informal	Enforced	Enforced
Delegation chains	No	Shipped, not constitutional	Constitutional
Cross-run decision carryover	No	Shipped, not constitutional	Constitutional
Parallel turns	No	Shipped, not constitutional	Constitutional
Run event lifecycle (events.jsonl)	No	Shipped, not constitutional	Constitutional

To migrate a legacy v3 project into the current governed contract:

agentxchain migrate --yes

This rewrites a legacy v3 config into governed config schema 1.0, creates governed .agentxchain/state.json at schema 1.1, archives legacy coordination artifacts, and starts the migrated project in paused human:migration-review state. It does not backfill legacy history into governed history, and it does not create coordinator state until you explicitly initialize multi-repo coordination.