diff --git a/.changeset/governance-human-override-declaration.md b/.changeset/governance-human-override-declaration.md new file mode 100644 index 00000000000..e7622e3a33f --- /dev/null +++ b/.changeset/governance-human-override-declaration.md @@ -0,0 +1,11 @@ +--- +"adcontextprotocol": minor +--- + +Governance (3.4): declare `plans[].human_override` on `sync_plans` and state the human-review downgrade rule (#9068). + +- **Schema.** The `sync_plans` plan item declares `human_override`: an object with `reason` (non-empty string) and `approver` (string), both required, an optional `approved_at` (date-time), and open to additional members. It is part of the `plan_hash` preimage, as the specification already said. +- **Rule.** The campaign governance specification ("Human review required") now states normatively that a re-sync that would change a stored plan from human review required to not required MUST carry `human_override`, and that without it the governance agent MUST reject the sync with `VALIDATION_ERROR` and leave the plan unchanged. The rule follows the stored state: it applies whether the re-sync sends `false` or omits the flag, and whether the stored `true` was set by the caller or derived from policy. A governance agent MAY apply stricter checks (minimum reason length, `approved_at` freshness, `approver` as an email address or an authenticated identity). `human_override` never permits `false` while a triggering policy is present. The governance agent stores the artifact and keeps it when a later re-sync omits it; `plan_hash` is still computed over the plan as supplied, so a buyer SHOULD resend `human_override` on later re-syncs while the flag stays lowered. +- **Docs and compliance.** The `sync_plans` task page lists the field and the rejected downgrade under `VALIDATION_ERROR`, the Annex III page points at the normative rule, and the new `governance/human_review_downgrade` storyboard checks that lowering the flag without `human_override` (by omission or by `false`) is rejected and that the same re-sync with it succeeds. + +**Migration note.** `sync-plans-request.json` is `x-status: experimental`. The declaration narrows what validates against 3.2.11 and 3.3: the plan item was open and `human_override` undeclared, so any value validated. A string (for example `"approved by legal"`), a `reason`-only object, an object without `approver`, and an empty `reason` no longer validate. This documents existing behaviour rather than changing it: "reason + approver" is the only shape AdCP has ever described (3.0 release notes, the Annex III obligations page), and the reference governance agent has required that shape, and rejected every other one, since 3.0. Before: `"human_override": "approved by legal"`. After: `"human_override": { "reason": "Campaign narrowed to brand awareness; no housing offers remain.", "approver": "legal@pinnacle.example" }`. diff --git a/.github/workflows/training-agent-storyboards.yml b/.github/workflows/training-agent-storyboards.yml index 028e4cac62d..0f4cecc73c4 100644 --- a/.github/workflows/training-agent-storyboards.yml +++ b/.github/workflows/training-agent-storyboards.yml @@ -444,6 +444,7 @@ jobs: requirements=( "governance/failed_outcome_audit_persistence:4:0" "governance/budget_periods:7:0" + "governance/human_review_downgrade:4:0" ) for requirement in "${requirements[@]}"; do storyboard_id="${requirement%%:*}" diff --git a/docs/governance/annex-iii-obligations.mdx b/docs/governance/annex-iii-obligations.mdx index 47e94551743..ec2302430a8 100644 --- a/docs/governance/annex-iii-obligations.mdx +++ b/docs/governance/annex-iii-obligations.mdx @@ -61,7 +61,7 @@ When a campaign plan declares any of the following, the governance agent MUST se If any Annex III category resolves but `brand.data_subject_contestation` is missing, the governance agent MUST emit a critical finding — Art 22(3) cannot be discharged without a contact point. -This is enforced by the policy framework, not by the buyer. A buyer cannot opt out of human review by omitting the flag — if the resolved policies require it, the governance agent sets it. A buyer who previously declared `human_review_required: true` cannot downgrade it on re-sync without an explicit `human_override` artifact (reason + approver). +This is enforced by the policy framework, not by the buyer. A buyer cannot opt out of human review by omitting the flag — if the resolved policies require it, the governance agent sets it. A re-sync cannot lower a plan that required human review, whether the buyer declared the flag or the governance agent derived it, unless it carries a `human_override` artifact naming a reason and an approver. The [campaign governance specification](/docs/governance/campaign/specification#human-review-required) states the rule normatively. ### `reallocation_threshold` vs. `human_review_required` diff --git a/docs/governance/campaign/specification.mdx b/docs/governance/campaign/specification.mdx index 358dd343d11..cbdd6dca485 100644 --- a/docs/governance/campaign/specification.mdx +++ b/docs/governance/campaign/specification.mdx @@ -164,6 +164,16 @@ This field is distinct from `budget.reallocation_threshold`: Callers MAY set `human_review_required: true` explicitly on a plan even when no triggering policy is present. Callers MUST NOT set it to `false` to override a policy that requires human review — the governance agent re-evaluates the flag from resolved policies on every sync and rejects a caller-supplied `false` when a triggering policy is present. +A [`sync_plans`](/docs/governance/campaign/tasks/sync_plans) that would change a stored plan from human review required to not required MUST carry a `human_override` object on that plan. Without it, the governance agent MUST reject the sync with [`VALIDATION_ERROR`](/docs/building/verification/compliance-catalog#error-code-validation-error) and leave the plan unchanged. The rule follows the stored state, not the request: + +- It applies whether the re-sync sends `false` or omits the flag. An omitted flag is derived, so a stored `true` that the re-sync derives as `false` is a downgrade. +- It applies whether the stored `true` was set by the caller or derived from the plan's policies. +- A re-sync that keeps the flag `true` or raises it needs no `human_override`, and neither does a sync of a plan whose stored state does not require human review. + +`human_override` carries a non-empty `reason` and an `approver`, both required, and an optional `approved_at` timestamp. A governance agent MAY apply stricter checks, such as a minimum `reason` length, a freshness window on `approved_at`, or requiring `approver` to be an email address or an identity it can authenticate. It rejects a `human_override` that fails them with the same `VALIDATION_ERROR`. `human_override` never permits `false` while a triggering policy or policy category is present; that rejection is unchanged. + +The governance agent stores `human_override` with the plan and keeps it when a later re-sync omits it. The [`plan_hash`](#canonicalization) preimage is still the plan as supplied, so a re-sync that omits `human_override` changes `plan_hash` and invalidates the plan's outstanding `governance_context` tokens. That fails safe, but a buyer SHOULD resend the same `human_override` on later re-syncs while the flag stays lowered. + ### Spend-commit invocation Buyer-side governance invocation is enforceable, not advisory. When a governance agent is configured on the plan, the buyer agent MUST invoke [`check_governance`](/docs/governance/campaign/tasks/check_governance) before sending any spend-commit request to a seller — full stop — producing an **intent-phase** `governance_context` token to attach to that request. The governance agent decides internally whether to auto-approve, apply conditions, deny, or escalate to human review per the plan's `budget.reallocation_threshold` and `human_review_required` fields. No dollar figures, no baseline arithmetic, no operator-declared floors appear in the invocation rule — those auto-approve fast-paths belong inside the governance agent's own policy, not in the buyer's decision about whether to call at all. diff --git a/docs/governance/campaign/tasks/sync_plans.mdx b/docs/governance/campaign/tasks/sync_plans.mdx index a93b9f7b5e9..a123686adbb 100644 --- a/docs/governance/campaign/tasks/sync_plans.mdx +++ b/docs/governance/campaign/tasks/sync_plans.mdx @@ -205,6 +205,7 @@ Each plan item a buyer supplies here is the preimage the governance agent hashes | `plans[].restricted_attributes_custom` | array | No | Additional restricted attributes not covered by the enum. Freeform strings for jurisdiction-specific restrictions (e.g., `financial_status`). | | `plans[].min_audience_size` | integer | No | Minimum audience segment size for k-anonymity. Applies to the estimated intersection audience when multiple criteria are used. | | `plans[].human_review_required` | boolean | No | When `true`, the governance agent escalates every action on the plan for human review. When omitted, the governance agent derives the value from the plan's resolved policies and policy categories. `false` is rejected when any of them requires human review. See [specification](/docs/governance/campaign/specification#human-review-required). | +| `plans[].human_override` | object | Conditional | Record of the human decision that permits lowering `human_review_required` from `true` to `false`. Required on a re-sync that would change a stored plan from human review required to not required, whether the re-sync sends `false` or omits the flag. Carries `reason` (non-empty string, required), `approver` (string, required) and `approved_at` (date-time, optional). Part of the `plan_hash` preimage; resend it on later re-syncs while the flag stays lowered. See [specification](/docs/governance/campaign/specification#human-review-required). | | `plans[].policy_ids` | array | No | Registry policy IDs to enforce for this plan. Each ID MUST appear at most once. Intersected with the plan's countries/regions to activate only geographically relevant policies. | | `plans[].custom_policies` | array | No | Campaign-specific policies using the `PolicyEntry` shape (`policy_id`, `enforcement`, `policy` text required). Additive only — cannot relax or override registry-sourced policies. A `policy_id` MUST NOT equal an ID in `policy_ids`. See [policy resolution](/docs/governance/campaign/specification#policy-resolution). | | `plans[].approved_sellers` | array/null | No | List of approved seller agent URLs. `null` means any seller. | @@ -289,7 +290,7 @@ Policy categories are distinct from `brand.industries`. Industries describe what |------|----------|-------------| | [`INVALID_REQUEST`](/docs/building/verification/compliance-catalog#error-code-invalid-request) | correctable | Plan is missing required fields or has invalid values, including a `flight.end` that is not later than `flight.start`, a repeated ID in `policy_ids`, and a `custom_policies[].policy_id` that equals an ID in `policy_ids`. For `budget.periods`, this covers a duplicate `budget_period_id`, overlapping or empty windows, a window outside `flight`, amounts above `budget.total`, and more than 366 periods. `error.field` identifies the offending plan field. | | [`REFERENCE_NOT_FOUND`](/docs/building/verification/compliance-catalog#error-code-reference-not-found) | correctable | Brand domain could not be resolved via the Brand Protocol. The governance agent cannot determine applicable compliance policies without a valid brand reference. `error.field` MUST identify the brand field that failed to resolve. | -| [`VALIDATION_ERROR`](/docs/building/verification/compliance-catalog#error-code-validation-error) | correctable | Cannot reduce budget below the amount already committed (on plan update), leave a dated commitment outside every budget period, or set a period `amount` below what is already committed to it. `error.field` identifies the budget field. | +| [`VALIDATION_ERROR`](/docs/building/verification/compliance-catalog#error-code-validation-error) | correctable | Cannot reduce budget below the amount already committed (on plan update), leave a dated commitment outside every budget period, or set a period `amount` below what is already committed to it. `error.field` identifies the budget field. Also returned when a re-sync would lower a stored plan from human review required to not required without a `human_override`, or with one that fails the governance agent's checks; the plan is left unchanged. | ## Related tasks diff --git a/scripts/run-storyboards-matrix.sh b/scripts/run-storyboards-matrix.sh index b7fa3a13e6c..4060d9c1893 100755 --- a/scripts/run-storyboards-matrix.sh +++ b/scripts/run-storyboards-matrix.sh @@ -342,6 +342,7 @@ REQUIRED_EXACT_CURRENT_SALES=( REQUIRED_EXACT_CURRENT_GOVERNANCE=( "governance/failed_outcome_audit_persistence:4:0" "governance/budget_periods:7:0" + "governance/human_review_downgrade:4:0" ) REQUIRED_CLEAN_CURRENT_SIGNALS=( "wholesale_feed_signals" diff --git a/static/compliance/source/protocols/governance/index.yaml b/static/compliance/source/protocols/governance/index.yaml index a06aa354bbe..029559d99f5 100644 --- a/static/compliance/source/protocols/governance/index.yaml +++ b/static/compliance/source/protocols/governance/index.yaml @@ -13,6 +13,7 @@ required_tools: requires_scenarios: - governance/failed_outcome_audit_persistence - governance/budget_periods + - governance/human_review_downgrade narrative: | The buyer's governance agent denies a media buy because it exceeds the agent's spending diff --git a/static/compliance/source/protocols/governance/scenarios/human_review_downgrade.yaml b/static/compliance/source/protocols/governance/scenarios/human_review_downgrade.yaml new file mode 100644 index 00000000000..eabd5ad1928 --- /dev/null +++ b/static/compliance/source/protocols/governance/scenarios/human_review_downgrade.yaml @@ -0,0 +1,180 @@ +id: governance/human_review_downgrade +version: "1.0.0" +introduced_in: "3.4" +title: "Governance requires human_override to lower human review on a re-sync" +category: campaign_governance +summary: "Verifies that a re-sync cannot take a plan out of human review without a human_override artifact: lowering the flag by omitting it or by sending false is rejected with VALIDATION_ERROR and leaves the plan unchanged, and the same re-sync carrying human_override succeeds." +track: campaign_governance +default_agent: governance + +required_tools: + - sync_plans + +narrative: | + A buyer registers a housing campaign. The plan declares the fair_housing + policy category and omits human_review_required, so the governance agent + derives it as true and escalates every action on the plan. + + The buyer then narrows the campaign and re-syncs the plan without the + category. With no triggering policy left, the flag would now derive as + false. The stored plan required human review, so lowering it is a + downgrade and needs a human_override artifact. The re-sync that omits the + flag is rejected with VALIDATION_ERROR. A second re-sync that sends + human_review_required false is rejected the same way, which also shows the + first rejection left the plan unchanged. + + Finally the buyer re-syncs with a human_override naming the reason and the + approver, and the governance agent accepts the sync. + +agent: + interaction_model: governance_agent + capabilities: + - campaign_governance + examples: + - "Buyer governance agent that enforces human review for regulated campaigns" + +caller: + role: buyer_agent + example: "Pinnacle Agency (buyer)" + +prerequisites: + description: "The caller can synchronize a plan that requires human review and re-sync the same plan." + test_kit: "test-kits/acme-outdoor.yaml" + +phases: + - id: register_plan + title: "Register a plan that requires human review" + steps: + - id: sync_regulated_plan + title: "Create a fair_housing plan with the flag omitted" + task: sync_plans + schema_ref: "governance/sync-plans-request.json" + response_schema_ref: "governance/sync-plans-response.json" + doc_ref: "/governance/campaign/tasks/sync_plans" + stateful: true + sample_request: + idempotency_key: "$generate:uuid_v4#human_review_downgrade_plan" + plans: + - plan_id: "human-review-downgrade-plan" + brand: + domain: "acmeoutdoor.example" + objectives: "Promote rental listings in a new residential development." + budget: + total: 25000 + currency: "USD" + reallocation_threshold: 5000 + flight: + start: "2099-01-01T00:00:00Z" + end: "2099-03-31T23:59:59Z" + countries: ["US"] + policy_categories: ["fair_housing"] + validations: + - check: response_schema + description: "Response matches sync-plans-response.json" + - check: field_value + path: "plans[0].plan_id" + value: "human-review-downgrade-plan" + description: "The plan is accepted; fair_housing makes the governance agent derive human review as required" + + - id: downgrade_without_override + title: "Lowering human review without human_override is rejected" + steps: + - id: resync_omits_flag + title: "Re-sync without the category and without the flag" + task: sync_plans + schema_ref: "governance/sync-plans-request.json" + response_schema_ref: "governance/sync-plans-response.json" + doc_ref: "/governance/campaign/tasks/sync_plans" + stateful: true + expect_error: true + negative_path: payload_well_formed + sample_request: + idempotency_key: "$generate:uuid_v4#human_review_downgrade_omit" + plans: + - plan_id: "human-review-downgrade-plan" + brand: + domain: "acmeoutdoor.example" + objectives: "Promote rental listings in a new residential development." + budget: + total: 25000 + currency: "USD" + reallocation_threshold: 5000 + flight: + start: "2099-01-01T00:00:00Z" + end: "2099-03-31T23:59:59Z" + countries: ["US"] + validations: + - check: error_code + value: "VALIDATION_ERROR" + description: "The stored plan required human review and the re-sync would derive it as not required; an omitted flag is a downgrade and needs human_override" + + - id: resync_sends_false + title: "Re-sync without the category and with human_review_required false" + task: sync_plans + schema_ref: "governance/sync-plans-request.json" + response_schema_ref: "governance/sync-plans-response.json" + doc_ref: "/governance/campaign/tasks/sync_plans" + stateful: true + expect_error: true + negative_path: payload_well_formed + sample_request: + idempotency_key: "$generate:uuid_v4#human_review_downgrade_false" + plans: + - plan_id: "human-review-downgrade-plan" + brand: + domain: "acmeoutdoor.example" + objectives: "Promote rental listings in a new residential development." + budget: + total: 25000 + currency: "USD" + reallocation_threshold: 5000 + flight: + start: "2099-01-01T00:00:00Z" + end: "2099-03-31T23:59:59Z" + countries: ["US"] + human_review_required: false + validations: + - check: error_code + value: "VALIDATION_ERROR" + description: "An explicit false is the same downgrade; the rejection also shows the previous rejected sync left the stored plan requiring human review" + + - id: downgrade_with_override + title: "Lowering human review with human_override succeeds" + steps: + - id: resync_with_override + title: "Re-sync with human_review_required false and a human_override" + task: sync_plans + schema_ref: "governance/sync-plans-request.json" + response_schema_ref: "governance/sync-plans-response.json" + doc_ref: "/governance/campaign/tasks/sync_plans" + stateful: true + sample_request: + idempotency_key: "$generate:uuid_v4#human_review_downgrade_override" + plans: + - plan_id: "human-review-downgrade-plan" + brand: + domain: "acmeoutdoor.example" + objectives: "Promote rental listings in a new residential development." + budget: + total: 25000 + currency: "USD" + reallocation_threshold: 5000 + flight: + start: "2099-01-01T00:00:00Z" + end: "2099-03-31T23:59:59Z" + countries: ["US"] + human_review_required: false + human_override: + reason: "Campaign narrowed to brand awareness; no housing offers or eligibility decisions remain." + approver: "legal@acmeoutdoor.example" + validations: + - check: response_schema + description: "Response matches sync-plans-response.json" + - check: field_value + path: "plans[0].plan_id" + value: "human-review-downgrade-plan" + description: "The downgrade is accepted once it carries a human_override with a reason and an approver" + - check: field_value + path: "plans[0].status" + value: "active" + description: "The re-synced plan is active" diff --git a/static/schemas/source/governance/sync-plans-request.json b/static/schemas/source/governance/sync-plans-request.json index 627dbd9fe29..9fcbf0a9fa6 100644 --- a/static/schemas/source/governance/sync-plans-request.json +++ b/static/schemas/source/governance/sync-plans-request.json @@ -311,6 +311,32 @@ "type": "boolean", "description": "When true, the governance agent MUST escalate any action on this plan for human review before execution — regardless of budget. Required by regulations that prohibit solely automated decisions affecting data subjects (GDPR Art 22, EU AI Act Annex III): credit, insurance pricing, recruitment, housing allocation. Governance agents MUST set this to true automatically when any resolved policy or policy_category has requires_human_review: true. When a plan omits this field, the governance agent derives it from the plan's resolved policies and policy categories; a caller-supplied false is rejected when any of them requires human review. Distinct from budget.reallocation_threshold, which only governs budget reallocation autonomy — human_review_required covers decisions affecting individuals (targeting, creative, delivery)." }, + "human_override": { + "type": "object", + "description": "Record of the human decision that permits lowering human_review_required from true to false on a re-sync. A sync that would change a stored plan from human review required to not required, whether it sends false or omits the flag, MUST carry this object; without it the governance agent rejects the sync with VALIDATION_ERROR and leaves the plan unchanged. It never permits false while a resolved policy or policy category requires human review. A governance agent MAY apply stricter checks, such as a minimum reason length, a freshness window on approved_at, or binding approver to an authenticated identity. Part of the plan_hash preimage: a buyer SHOULD resend it on later re-syncs while the flag stays lowered, because omitting it changes plan_hash.", + "x-added-in": "3.4.0", + "properties": { + "reason": { + "type": "string", + "minLength": 1, + "description": "Why the plan no longer needs human review." + }, + "approver": { + "type": "string", + "description": "Who approved lowering the flag. A governance agent MAY require an email address or bind this to an authenticated identity." + }, + "approved_at": { + "type": "string", + "format": "date-time", + "description": "When the approver approved lowering the flag." + } + }, + "required": [ + "reason", + "approver" + ], + "additionalProperties": true + }, "custom_policies": { "type": "array", "items": { diff --git a/tests/sync-plans-human-review.test.cjs b/tests/sync-plans-human-review.test.cjs index 39c5abd6139..a6f458ba7b6 100644 --- a/tests/sync-plans-human-review.test.cjs +++ b/tests/sync-plans-human-review.test.cjs @@ -108,3 +108,55 @@ test('a default-materializing consumer leaves an omitted flag omitted on a regul assert.equal('human_review_required' in instance.plans[0], false, name); } }); + +// #9068: human_override is the artifact a re-sync carries to lower the flag +// from true to false. Its shape is normative; the downgrade rule is in +// docs/governance/campaign/specification.mdx#human-review-required. +const OVERRIDE = { + reason: 'Campaign scope narrowed to brand awareness; no housing offers remain.', + approver: 'legal@acme.example', +}; + +test('human_override is declared on the plan item with reason and approver required', () => { + const field = planItem().properties.human_override; + assert.equal(field.type, 'object'); + assert.deepEqual([...field.required].sort(), ['approver', 'reason']); + assert.equal(field.properties.reason.type, 'string'); + assert.equal(field.properties.reason.minLength, 1); + assert.equal(field.properties.approver.type, 'string'); + assert.equal(field.properties.approved_at.format, 'date-time'); + assert.equal(field.additionalProperties, true); + assert.equal(field['x-added-in'], '3.4.0'); + assert.match(field.description, /VALIDATION_ERROR/); + assert.match(field.description, /plan_hash/); +}); + +test('a plan with a well-formed human_override validates', async () => { + const validate = await compile(); + assert.equal(validate(request({ human_override: OVERRIDE })), true, errors(validate)); + assert.equal( + validate(request({ human_review_required: false, human_override: { ...OVERRIDE, approved_at: '2026-10-01T09:30:00Z' } })), + true, + errors(validate), + ); + assert.equal( + validate(request({ human_override: { ...OVERRIDE, ticket: 'LEGAL-1234' } })), + true, + `extra members stay open: ${errors(validate)}`, + ); +}); + +test('human_override shapes that 3.2.11 accepted and the declaration narrows are rejected', async () => { + const validate = await compile(); + const rejected = { + 'a string': 'approved by legal', + 'a reason-only object': { reason: OVERRIDE.reason }, + 'an approver-only object': { approver: OVERRIDE.approver }, + 'an empty reason': { ...OVERRIDE, reason: '' }, + 'a non-string approver': { ...OVERRIDE, approver: 42 }, + 'an approved_at that is not a date-time': { ...OVERRIDE, approved_at: 'yesterday' }, + }; + for (const [name, value] of Object.entries(rejected)) { + assert.equal(validate(request({ human_override: value })), false, name); + } +});