Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .changeset/governance-coherence-follow-up.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
"adcontextprotocol": patch
---

Campaign governance (experimental `governance.campaign`): follow-up errata found during the coherence sweep (adcp#8733, PR 4). Each edit follows a rule that is already stated elsewhere in the specification or schemas. No schema property, enum member or `plan_hash` rule changes.

- **Human-review trigger list.** The trust page, known limitations and the FAQ name all five schema triggers: `fair_housing`, `fair_lending`, `fair_employment` and `pharmaceutical_advertising` in `policy_categories`, and `eu_ai_act_annex_iii` in `policy_ids`. The FAQ no longer describes 3.0 in the future tense, and says that an omitted flag is accepted from 3.3.
- **Who sets the flag.** The `requires_human_review` descriptions in `policy-category-definition.json` and `policy-entry.json` say the governance agent sets `plan.human_review_required`, as the specification does. The category description no longer says that a policy can override the category's setting: a policy adds the requirement and cannot remove it.
- **Reallocation fields.** `budget.reallocation_threshold` is no longer documented as always required. The schema requires exactly one of `reallocation_threshold` or `reallocation_unlimited: true`, and the `sync_plans` field table now lists both. The reallocation table and the `reallocation_threshold` description point to `reallocation_unlimited: true` for unlimited reallocation, because a threshold equal to `total` tightens when `total` changes.
- **Overview page.** Advisory mode is described as returning `approved` with findings, and the "Execute" step and the image description no longer say budget is reserved.
- **Audit logs.** The audit-trail page and the `entries[].mode` description no longer refer to a closed issue or to mode as a plan property. The `entries[].mode` description no longer mentions a `governed_actions[].mode` field that does not exist. The specification and the audit-trail page now state the same strength as the schema: a governance agent SHOULD record the mode on check entries, and outcome entries carry none.
- **Mode on the response.** The specification no longer says that governance mode is "not a protocol-level field". The `check_governance` response has carried an optional `mode` property since 3.1, and the task page documents it. The specification now says that mode is agent configuration, that no request carries it, and that the agent may report it on the response. Callers still MUST NOT branch on it.
- **Delegation expiry.** The `delegations[].expires_at` description said that the governance agent denies an expired delegate's actions. It now follows the plan-access rule: a re-check that presents a context issued for the plan, and an execution check on an action the agent proposed, are `denied`, and any other check from that agent returns `PLAN_NOT_FOUND`.

Training agent: the `mode` property on its `sync_plans` tool is described as a sandbox test control. Its behaviour is unchanged.
2 changes: 1 addition & 1 deletion docs/faq.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ The full crosswalk is in [Why adagents.json instead of ads.txt](/docs/governance
<Accordion title="Can an AI agent autonomously buy credit, insurance, housing, or employment ads?">
These verticals fall under GDPR Art 22, EU AI Act Annex III, and US FHA / ECOA / EEOC. The policy-category mechanism already ships with `fair_housing`, `fair_lending`, and `fair_employment` entries in the registry.

AdCP 3.0 GA will require campaigns declaring a regulated policy category to run with human review — `authority_level: agent_full` will not be accepted — with an Annex III category taxonomy and a data-subject contestation path added at the same time. Tracked in [#2310](https://github.com/adcontextprotocol/adcp/issues/2310). Until that ships, enforcement depends on the governance agent implementation, not a schema invariant. See the [governance overview](/docs/governance/overview) for the full model.
Since AdCP 3.0 the `sync_plans` schema rejects `human_review_required: false` on a plan that declares `fair_housing`, `fair_lending`, `fair_employment` or `pharmaceutical_advertising` in `policy_categories`, or `eu_ai_act_annex_iii` in `policy_ids` ([#2310](https://github.com/adcontextprotocol/adcp/issues/2310)). Through 3.2.x the schema also required the flag to be `true` on such a plan. From 3.3 the flag may be omitted, and the governance agent then sets it. Other regulated categories depend on the governance agent implementation, not a schema invariant. See the [governance overview](/docs/governance/overview) for the full model.
</Accordion>

<Accordion title="Who governs AdCP?">
Expand Down
2 changes: 1 addition & 1 deletion docs/governance/campaign/audit-trail.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -314,7 +314,7 @@ The trade-off:
| `advisory` | Full velocity | Findings surface but don't block | Rolling out a new policy; observing behavior before tightening |
| `audit` | Full velocity | Findings logged silently | Backstop telemetry; never the only governance posture |

The agent's mode can change during a plan's lifetime. A different `mode` on two audit entries reflects a change to the governance agent's configuration, not a plan revision — the governance decisions in the audit trail tell the truth about how each historical buy was governed. The operating mode should be visible on every audit entry; today it appears on the per-`check_governance` response but not consistently on `get_plan_audit_logs` responses ([#3156](https://github.com/adcontextprotocol/adcp/issues/3156)).
The agent's mode can change during a plan's lifetime. A different `mode` on two audit entries reflects a change to the governance agent's configuration, not a plan revision — the governance decisions in the audit trail tell the truth about how each historical buy was governed. A governance agent SHOULD record the mode in force on each check entry, as `entries[].mode` on `get_plan_audit_logs` responses. Outcome entries carry no mode. The mode also appears on the `check_governance` response.

## What the protocol guarantees

Expand Down
10 changes: 6 additions & 4 deletions docs/governance/campaign/specification.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -87,13 +87,15 @@ When `purchase_type` is omitted, the governance agent assumes `media_buy`.

### Budget reallocation

`budget.reallocation_threshold` (required number) governs budget reallocation autonomy. It does not cover mandatory human review of decisions that affect data subjects — for that, see the plan-level `human_review_required` field.
`budget.reallocation_threshold` (a number, required unless `budget.reallocation_unlimited` is `true`; the two are mutually exclusive) governs budget reallocation autonomy. It does not cover mandatory human review of decisions that affect data subjects — for that, see the plan-level `human_review_required` field.

| Value | Meaning |
|-------|---------|
| `0` | Every reallocation requires human approval |
| positive number below `budget.total` | Agent may reallocate up to this amount without escalation; larger moves escalate for human review |
| equal to `budget.total` (or greater) | Agent may reallocate freely within the plan's total budget |
| equal to `budget.total` (or greater) | Agent may reallocate freely within the plan's total budget, until `budget.total` changes. For a deliberate full-autonomy declaration, use `budget.reallocation_unlimited: true` |

With `budget.reallocation_unlimited: true` and no threshold, the agent may reallocate freely within the plan's total budget, and the declaration does not tighten when `budget.total` changes.

### Budget allocations

Expand Down Expand Up @@ -875,7 +877,7 @@ The seller stores these endpoints and presents the credentials when calling `che

### Governance modes

Governance mode (audit, advisory, enforce) is an internal implementation detail of the governance agent, not a protocol-level field. The caller sends `check_governance` and acts on the verdict without needing to know what mode produced it. Intent checks may return `approved`, `denied`, or `conditions`; execution checks return `approved` or `denied`.
Governance mode (audit, advisory, enforce) is configuration of the governance agent. No request carries it, and it is not a plan field. The caller sends `check_governance` and acts on the verdict; it does not need to know which mode produced it. Intent checks may return `approved`, `denied`, or `conditions`; execution checks return `approved` or `denied`.

This means:
- A governance agent in audit mode internally returns `approved` with findings attached, with the two exceptions below
Expand All @@ -884,7 +886,7 @@ This means:

Two outcomes do not depend on mode. Plans with `human_review_required: true` escalate in every mode. A failed `approved_sellers` or `delegations` evaluation is `denied` in every mode, including: an intent check whose target is not in `approved_sellers`, an execution check by a caller that is not the audience preserved from the approved intent or that has since been removed from `approved_sellers`, an execution check whose original intent was made by a buyer that no longer holds a current delegation, an intent check by a buyer-side caller that can access the plan but is neither its owner nor a current delegate, and an intent check by a delegate that acts outside the `authority`, `budget_limit` or `markets` of its delegation.

Mode is configured by the buyer's policy team on the governance agent itself, not via the protocol. The governance agent MAY include mode information in its audit logs or `get_plan_audit_logs` response for post-hoc analysis, but callers MUST NOT branch behavior based on mode — they act on the status they receive.
Mode is configured by the buyer's policy team on the governance agent itself, not via the protocol. The governance agent MAY report the mode in force on the `check_governance` response (`mode`), and SHOULD record it on each check entry of its `get_plan_audit_logs` response (`entries[].mode`) for post-hoc analysis; outcome entries carry no mode. Callers MUST NOT branch behavior based on mode — they act on the status they receive.

See the [safety model](/docs/governance/campaign/safety-model) for the crawl-walk-run adoption path.

Expand Down
3 changes: 2 additions & 1 deletion docs/governance/campaign/tasks/sync_plans.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,8 @@ Each plan item a buyer supplies here is the preimage the governance agent hashes
| `plans[].budget.total` | number | Yes | Total authorized budget. |
| `plans[].budget.currency` | string | Yes | ISO 4217 currency code. |
| `plans[].budget.accounting_mode` | enum | No | `gross_commitment` (default) restores reusable headroom only for verified decommitments. `verified_net_cost` also restores it for verified refunds and credits. Both preserve original gross commitments for anti-fragmentation history. |
| `plans[].budget.reallocation_threshold` | number | Yes | Amount the agent may reallocate without escalation. `0` requires human approval for every reallocation; a value at or above `budget.total` is effectively unlimited. See [specification](/docs/governance/campaign/specification#budget-reallocation). |
| `plans[].budget.reallocation_threshold` | number | Conditional | Amount the agent may reallocate without escalation. `0` requires human approval for every reallocation; a value at or above `budget.total` is effectively unlimited. Required unless `reallocation_unlimited` is `true`. See [specification](/docs/governance/campaign/specification#budget-reallocation). |
| `plans[].budget.reallocation_unlimited` | boolean | Conditional | Set to `true` to allow the orchestrator to reallocate without any limit up to `total`. Mutually exclusive with `reallocation_threshold`. Use this for deliberate full-autonomy declarations rather than setting `reallocation_threshold: total` (which silently tightens when `total` changes). |
| `plans[].budget.per_seller_max_pct` | number | No | Maximum percentage of budget that can go to a single seller. |
| `plans[].budget.allocations` | object | No | Optional per-purchase-type budget partitions. Keys are purchase types (`media_buy`, `rights_license`, `signal_activation`, `creative_services`), values are objects with `amount`. When present, the governance agent validates spend against both the per-type allocation and the overall total. When absent, all spend counts against the single total regardless of purchase type. Allocations are guardrails, not hard partitions -- the sum of allocations MAY differ from the total. |
| `plans[].budget.periods` | array | No | Optional budget partition across time. Each entry is a half-open `[start, end)` window with its own `amount`, inside the plan `flight` and non-overlapping; amounts sum to at most `budget.total`. When present, dated commitments must fit the period that contains their whole flight. See [Budget periods](#budget-periods). |
Expand Down
8 changes: 5 additions & 3 deletions docs/governance/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -243,15 +243,17 @@ The callers (orchestrator, sellers) never changed their code. They always acted

<Accordion title="Budget commitment phases">

<img src="/images/concepts/budget-commitment-phases.png" alt="Three-step diagram showing proposed (dotted outline, hypothetical check), execute (solid tag, budget reserved), and committed (ledger records actual spend)" style={{ width: '100%', borderRadius: '12px', marginBottom: '1rem' }} />
<img src="/images/concepts/budget-commitment-phases.png" alt="Three-step diagram showing proposed (dotted outline, hypothetical check), execute (solid tag, amount authorized, labelled 'reserved' in the image), and committed (ledger records actual spend)" style={{ width: '100%', borderRadius: '12px', marginBottom: '1rem' }} />

In the diagram, "reserved" means the authorized amount. Checks do not place a hold on budget.

Budget tracking has three phases:

1. **Proposed**: `check_governance` evaluates whether the amount fits within the plan. No money reserved — this is a hypothetical check.
2. **Execute**: The seller runs the campaign. The governance agent tracks the authorized amount as reserved, but actual spend may differ.
2. **Execute**: The seller runs the campaign. Nothing is held between the check and the outcome: the plan's committed total does not change until the outcome is reported, and actual spend may differ from the authorized amount.
3. **Committed**: `report_plan_outcome` settles the authorization. The ledger uses governance-owned approved state; a seller-side purchase execution check can narrow the amount before commit, while a buyer report alone cannot restore headroom.

A \$25,000 intent that the seller prepares at \$24,850 frees the \$150 only when that prepared amount passes the seller-side purchase execution check. A buyer-reported lower number alone is audit evidence, not authority to release budget.
A \$25,000 intent that the seller prepares at \$24,850 commits \$24,850 rather than \$25,000 only when that prepared amount passes the seller-side purchase execution check. A buyer-reported lower number alone is audit evidence, not authority to release budget.

</Accordion>

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/known-limitations.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ Request-specific configured offers are not a gap: canonical products carry no `i

## Governance

- **Regulated-category human review is enforced at the schema level for four named categories, at the governance-agent level for everything else.** AdCP rejects `human_review_required: false` at the schema level on campaigns that declare `fair_housing`, `fair_lending`, `fair_employment`, or `pharmaceutical_advertising` (the original three shipped via [#2310](https://github.com/adcontextprotocol/adcp/issues/2310)). A plan that omits the flag passes the schema, and the governance agent sets it. Any other regulated category — political, gambling, alcohol, tobacco, financial, crypto, cannabis/CBD, firearms, dietary-supplement health claims, child-directed — relies on the governance-agent implementation rather than a category-specific schema invariant.
- **Regulated-category human review is enforced at the schema level for four named categories and the `eu_ai_act_annex_iii` policy, at the governance-agent level for everything else.** AdCP rejects `human_review_required: false` at the schema level on campaigns that declare `fair_housing`, `fair_lending`, `fair_employment`, or `pharmaceutical_advertising` (the original three shipped via [#2310](https://github.com/adcontextprotocol/adcp/issues/2310)), and on plans whose `policy_ids` contain `eu_ai_act_annex_iii`. A plan that omits the flag passes the schema, and the governance agent sets it. Any other regulated category — political, gambling, alcohol, tobacco, financial, crypto, cannabis/CBD, firearms, dietary-supplement health claims, child-directed — relies on the governance-agent implementation rather than a category-specific schema invariant.
- **No protocol-mandated HITL on `sync_catalogs` or `sync_creatives`.** The universal task-lifecycle mechanism is available; no normative rule requires a human gate. `acquire_rights` is governed via the campaign-governance path ([purchase phase](/docs/governance/campaign/specification#governance-phases)) when the buyer's plan is configured for it. See [How human-in-the-loop enters the protocol](/docs/governance/embedded-human-judgment#how-human-in-the-loop-enters-the-protocol) for the two channels and the EHJ register for the normative rules on `check_governance`, `TERMS_REJECTED`, and lifecycle tasks.
- **Other regulated categories have no category-specific schema treatment.** Political advertising, gambling, alcohol, tobacco, financial promotions (including crypto and digital assets), cannabis/CBD, firearms, dietary-supplement health claims, and advertising directed at children rely on the general [campaign-governance](/docs/governance/campaign/specification) mechanism (HITL gates, governance tasks) rather than category-specific schema rules. `pharmaceutical_advertising` is the exception: it joins housing, lending, and employment in the schema-level human-review constraint. Regionally specific disclosure requirements (e.g., UK FCA s.21, EU MiCA, political ad registries, COPPA, the UK Children's Code, GDPR Article 8) sit in the seller's delivery stack and the buyer's compliance posture, not the protocol.

Expand Down
Loading
Loading