# Coordination Protocol

How agents work together without stepping on each other. Read alongside [`roles.md`](roles.md),
[`../roadmap/workstreams.md`](../roadmap/workstreams.md), and [`../AGENTS.md`](../AGENTS.md).

## 1. Claim before you build
- Take an item from [`task-board.md`](task-board.md), set its owner and status to `in-progress`.
- Respect `blocked-by`. Do not start blocked work; help unblock it instead.
- Keep items small and single-responsibility.

## 2. Contracts are sacred
Workstreams communicate through **interfaces** (listed in [`../roadmap/workstreams.md`](../roadmap/workstreams.md)):
the ServiceDefinition schema, StorageClasses, the network policy/egress rendering, TLS issuer +
Gateway, the observability contract, the update-policy contract.

- **Consume** a contract freely.
- **Change** a contract only by: (1) proposing the change on the task board with the affected
  workstreams tagged, (2) getting the owning role's sign-off, (3) updating the spec that defines the
  contract in the *same* change. Never silently break a downstream consumer.
- The **ServiceDefinition schema** is the highest-traffic contract; treat schema changes as
  platform-wide events.

## 3. Decisions vs. discussion — and the no-spec-change rule
- **You may not modify the specifications** (`docs/`, requirements, accepted ADRs, roadmap) — they
  are human-owned and immutable to agents (R-TEST-06, [`../AGENTS.md` §11](../AGENTS.md)).
- Anything that changes a locked choice ⇒ **draft** a superseding ADR and **escalate to the human**
  ([`../decisions/README.md`](../decisions/README.md)); do not self-approve or merge it.
- Genuine unknowns, or a spec that is wrong/blocking/ambiguous ⇒ **stop and escalate** on the task
  board as an **Open Question (OQ-n)** for the human to resolve in the spec; don't bury ambiguity in
  an implementation and don't patch the spec yourself.

## 4. Definition of done
Nothing is "done" until its **automated, reproducible behavior test passes green** in **dev/test**,
committed with the change and tagged to its requirement IDs ([`definition-of-done.md`](definition-of-done.md),
[`../docs/14-testing-and-conformance.md`](../docs/14-testing-and-conformance.md)). "Merged" ≠ "done";
"demonstrated manually" ≠ "done". You write the test as well as the implementation.

## 5. Phase discipline
- Only work items in the **active phase(s)** ([`../roadmap/phases.md`](../roadmap/phases.md)) unless
  explicitly parallelizable.
- Respect entry gates; don't start a phase whose predecessor's exit criteria aren't demonstrated.
- **Prod (Phase 7) is closed** until the operator opens it.

## 6. Handoffs
When your output feeds another workstream:
- State the interface you're delivering and where it's documented.
- Provide the demonstrable proof (the gate you passed) so the consumer can trust it.
- If you changed a shared contract, announce it on the board with consumers tagged.

## 7. Conflict resolution
1. Re-read the source-of-truth hierarchy ([`../AGENTS.md` §2](../AGENTS.md)); the higher document
   wins.
2. If specs genuinely conflict or are silent, escalate to the **Platform Architect** to amend the
   spec/ADR — fix the documents first, then build.
3. Never resolve a conflict by silently picking an interpretation in code.

## 8. Safety rails that never bend
- Default-deny + VPN kill-switch are **fail-closed** — if unsure, deny/close.
- Secrets stay encrypted; never printed.
- Nothing that risks data ships without a tested backup/restore behind it.
- No click-ops except ADR-sanctioned bootstrap steps.
- **Specs are immutable to you**; a spec you can't meet is an escalation, never an edit.
- **Never weaken a test or a requirement to get green** — that's a defect, not progress.

## 9. Communication artifacts
- **task-board.md** — the live who's-doing-what + status + blockers.
- **specs/ADRs** — durable decisions and contracts.
- **PR descriptions** — reference requirement IDs, specs, ADRs, and the gate demonstrated.
Keep these three in sync; they are how independent agents stay coherent.