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
17 changes: 17 additions & 0 deletions .changeset/governance-coherence-decisions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
---
"adcontextprotocol": minor
---

Campaign governance (experimental `governance.campaign`): settle the rules the specification contradicted or left undefined (adcp#8733, PR 2 of 3). These are normative decisions of the Governance working group. No wire field, enum member or `plan_hash` rule changes. This is a change within the 3.3 pre-release.

- **Budget cut below committed spend.** A `sync_plans` that reduces `budget.total` (or a period `amount`) below the amount already committed is rejected with `VALIDATION_ERROR` and leaves the plan unchanged. Before, the specification said the sync was accepted and flagged on the next check, while the task page said it was rejected.
- **Unapproved seller or undelegated caller on `check_governance`.** A failed `approved_sellers` or `delegations` evaluation for an authenticated caller is returned as a `denied` verdict with a finding and a `check_id`, so the attempt can be audited. This holds in every governance mode. A plan is accessible to its owner principal, to a current delegate, and to a caller that presents a `governance_context` or `consultation_context` issued for that plan. Any other caller receives `PLAN_NOT_FOUND`, the same response as for an unknown `plan_id`, and writes no audit entry. Before, the task page listed `PERMISSION_DENIED` for these cases. `check_governance` still returns `PERMISSION_DENIED` when the caller is unauthenticated or its authenticated identity does not match `caller`. Callers that branch on the error code for the authority cases must also handle the verdict.
- **Human review in every mode.** Audit and advisory mode no longer describe an agent that always returns `approved`: plans with `human_review_required: true` escalate in every mode, and a failed `approved_sellers` or `delegations` evaluation is `denied` in every mode.
- **`plan_id` namespace.** A `plan_id` is unique per owner principal. Two principals may use the same `plan_id`, and a `sync_plans` never reads, changes or reveals another principal's plan.
- **`execute_only`.** A pre-approved action is one whose opaque action binding already holds an approved intent check in the plan's lifecycle. An `execute_only` delegate may act only on such an action, which includes `accept_proposal` for it. The governance agent MUST deny an intent check from an `execute_only` delegate that would create a new binding or increase committed spend.
- **Regions-restricted plans.** An action with no geographic targeting, or with country-level targeting only, is outside a regions-restricted plan: an intent check returns `conditions` naming the region constraint, and an execution check returns `denied`.
- **Unresolvable registry policy ID.** `sync_plans` returns `REFERENCE_NOT_FOUND` when a registry policy ID in `policy_ids` cannot be resolved.
- **Three re-call rule.** "The same action" means re-checks that carry the same `consultation_context`.
- **Explicit `human_review_required: false`.** The `sync_plans` error table states that it is rejected with `VALIDATION_ERROR` on a plan that requires human review.

Training agent: `sync_plans` now rejects a `budget.total` reduced below committed spend, and `check_governance` returns the `denied` verdict for an authenticated execution caller that is not the audience preserved from the approved intent, and for a buyer-side caller whose delegation has ended. It no longer approves a failed `approved_sellers` or `delegations` evaluation in advisory or audit mode. For a plan that does not exist or that the caller cannot access, `check_governance` now returns the `PLAN_NOT_FOUND` error; it returned a `denied` verdict with a `plan_lookup` finding.
29 changes: 15 additions & 14 deletions docs/governance/campaign/audit-trail.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -176,15 +176,14 @@ Findings are how the audit trail communicates risk. Two patterns worth knowing:

### Security-shaped finding: an unauthorized seller

The plan declares `approved_sellers: ["https://ads.seller-approved.example"]`. A different seller calls `check_governance` and gets denied:
The plan declares `approved_sellers: ["https://ads.seller-approved.example"]`. A different seller calls `check_governance` with an execution check and gets denied:

```json
{
"$schema": "/schemas/governance/check-governance-response.json",
"status": "completed",
"check_id": "chk_0ac8d7de",
"check_type": "intent",
"plan_id": "plan_2027_apex_athletic",
"check_type": "execution",
"verdict": "denied",
"explanation": "Denied: Caller https://ads.seller-rogue.example is not in the plan's approved sellers list.",
"categories_evaluated": ["delegation_authority", "seller_compliance"],
Expand Down Expand Up @@ -230,7 +229,7 @@ The denial is also a coaching moment — the operator sees exactly what to fix.

## The operator's dial: enforce / advisory / audit

`mode` is governance agent configuration. The buyer's policy team sets it on the governance agent itself; it is not a plan field and is not sent in [`sync_plans`](/docs/governance/campaign/tasks/sync_plans). It is the operator's primary lever, and an agent that reports `mode` records the mode in force on each check entry. The same caller, same payload, same finding produces three different outcomes depending on mode.
`mode` is governance agent configuration. The buyer's policy team sets it on the governance agent itself; it is not a plan field and is not sent in [`sync_plans`](/docs/governance/campaign/tasks/sync_plans). It is the operator's primary lever, and an agent that reports `mode` records the mode in force on each check entry. The same caller, same payload and same finding produce three different outcomes depending on mode. The example is a buy that asks for more than the plan's total budget.

**`mode: "enforce"`** — the buy is blocked at the governance layer:

Expand All @@ -242,14 +241,14 @@ The denial is also a coaching moment — the operator sees exactly what to fix.
"check_type": "intent",
"plan_id": "plan_mode_enforce",
"verdict": "denied",
"explanation": "Denied: Caller https://ads.seller-rogue.example is not in the plan's approved sellers list.",
"categories_evaluated": ["delegation_authority", "seller_compliance"],
"explanation": "Denied: Requested budget $150000 exceeds plan total $100000.",
"categories_evaluated": ["delegation_authority", "budget_authority"],
"policies_evaluated": [],
"findings": [
{
"category_id": "seller_compliance",
"category_id": "budget_authority",
"severity": "critical",
"explanation": "Caller https://ads.seller-rogue.example is not in the plan's approved sellers list."
"explanation": "Requested budget $150000 exceeds plan total $100000."
}
]
}
Expand All @@ -268,13 +267,13 @@ The denial is also a coaching moment — the operator sees exactly what to fix.
"explanation": "Approved with 1 advisory finding(s).",
"expires_at": "2027-01-15T15:32:41Z",
"governance_context": "eyJhbGciOiJFZERTQSJ9.advisory.signature",
"categories_evaluated": ["delegation_authority", "seller_compliance"],
"categories_evaluated": ["delegation_authority", "budget_authority"],
"policies_evaluated": [],
"findings": [
{
"category_id": "seller_compliance",
"category_id": "budget_authority",
"severity": "critical",
"explanation": "Caller https://ads.seller-rogue.example is not in the plan's approved sellers list."
"explanation": "Requested budget $150000 exceeds plan total $100000."
}
]
}
Expand All @@ -293,18 +292,20 @@ The denial is also a coaching moment — the operator sees exactly what to fix.
"explanation": "All governance checks passed.",
"expires_at": "2027-01-15T15:32:41Z",
"governance_context": "eyJhbGciOiJFZERTQSJ9.audit.signature",
"categories_evaluated": ["delegation_authority", "seller_compliance"],
"categories_evaluated": ["delegation_authority", "budget_authority"],
"policies_evaluated": [],
"findings": [
{
"category_id": "seller_compliance",
"category_id": "budget_authority",
"severity": "critical",
"explanation": "Caller https://ads.seller-rogue.example is not in the plan's approved sellers list."
"explanation": "Requested budget $150000 exceeds plan total $100000."
}
]
}
```

Two outcomes do not move with the dial. A failed `approved_sellers` or `delegations` evaluation is `denied` in every mode, as in the [unauthorized seller](#security-shaped-finding-an-unauthorized-seller) example above, and plans with `human_review_required: true` escalate in every mode.

The trade-off:

| Mode | Velocity | Safety | When to use |
Expand Down
6 changes: 3 additions & 3 deletions docs/governance/campaign/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Without a governance layer on the buy side:

Campaign Governance fills this gap with three mechanisms: **plans** that define what's allowed (independent of the agent), **seller-side governance checks** that verify purchases independently of the buyer, and a **policy registry** that standardizes compliance rules across governance agents.

Governance supports incremental adoption — organizations configure their governance agent to start in audit mode (log everything, approve everything), move to advisory (flag violations without blocking), and eventually enforce (block on violations). See the [safety model](/docs/governance/campaign/safety-model) for the adoption path. Mode is internal to the governance agent, not a protocol field.
Governance supports incremental adoption — organizations configure their governance agent to start in audit mode (log findings without blocking on them), move to advisory (flag violations without blocking), and eventually enforce (block on violations). See the [safety model](/docs/governance/campaign/safety-model) for the adoption path and for the two outcomes that hold in every mode. Mode is internal to the governance agent, not a protocol field.

### Industry precedent

Expand Down Expand Up @@ -143,8 +143,8 @@ Governance agents support incremental adoption through their internal mode confi

In practice, organizations configure their governance agent to progress through three stages:

1. **Audit** — Log everything, approve everything. The governance agent evaluates fully but always returns `approved` with findings attached. The organization reviews findings to assess false positive rates and calibrate policies.
2. **Advisory** — Approve with prominent findings and recommended corrections. The decision is still unambiguously `approved`; humans review findings post-hoc.
1. **Audit** — Log findings without blocking on them. The governance agent evaluates fully but returns `approved` with findings attached, except in two cases that hold in every mode: plans with `human_review_required: true` escalate, and a failed `approved_sellers` or `delegations` evaluation is `denied`. The organization reviews findings to assess false positive rates and calibrate policies.
2. **Advisory** — Approve with prominent findings and recommended corrections. The decision is still `approved`; humans review findings post-hoc. The same two exceptions apply.
3. **Enforce** — Block on violations. The default for production governance.

This works the same way for a single brand buying direct and for a holding company with 35 brands and multiple agency partners.
Expand Down
4 changes: 2 additions & 2 deletions docs/governance/campaign/safety-model.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -59,8 +59,8 @@ Governance agents support three internal operating modes so organizations can bu

| Mode | What happens | Risk |
|------|-------------|------|
| **Audit** | Log everything, never block. Always returns `approved` with findings attached. | Zero. See what governance would flag without affecting live campaigns. |
| **Advisory** | Return `approved` with prominent findings and recommended corrections. | Minimal. Humans review findings post-hoc and act on them. |
| **Audit** | Log everything. Returns `approved` with findings attached, except in two cases that hold in every mode: plans with `human_review_required: true` escalate, and a failed `approved_sellers` or `delegations` evaluation is `denied`. | Lowest. See what governance would flag. Only the two cases named here affect live campaigns. |
| **Advisory** | Return `approved` with prominent findings and recommended corrections, with the same two exceptions. | Minimal. Humans review findings post-hoc and act on them. |
| **Enforce** | Block on violations. Require resolution before proceeding. | Production governance with full protection. |

Start in audit mode to evaluate false positive rates and calibrate policies. Move to advisory to test findings with real campaigns. Switch to enforce when confidence is established. The governance agent's audit logs record which mode was active for each check, so post-hoc analysis can distinguish audit-mode approvals from enforce-mode approvals.
Expand Down
Loading
Loading