Add `universal/governance.yaml` cross-cutting normative obligation

[bokelley]

Issue: add universal/governance.yaml cross-cutting normative obligation

Repo: adcontextprotocol/adcp
Type: spec gap (compliance / cross-cutting)
Severity: high (silently passing implementations are non-compliant)
Target: 3.x minor (purely additive — codifies behavior already expected)

Problem

The cross-cutting requirement "any mutating request whose account has registered governance agents MUST consult them before mutating" is encoded only inside individual specialism storyboards (e.g., compliance/specialisms/brand-rights/scenarios/governance_denied.yaml).

There is no universal/governance.yaml parallel to universal/idempotency.yaml. An agent author reading only the brand-rights chapter (or only the seller chapter, or only the signals chapter) cannot discover that this obligation exists. The first time most implementations hit it is when the storyboard fails — and even then the failure mode (missing GOVERNANCE_DENIED error code on a path the implementor didn't realize was governance-gated) is hard to triage without already knowing the rule.

Compare:

• idempotency_key is normative cross-cutting → has universal/idempotency.yaml, listed in the protocol-wide block of every spec preamble, called out in MUTATING_TASKS constants, has its own conformance baseline.
• Governance consultation is normative cross-cutting → has nothing equivalent. It's encoded as an emergent property of one storyboard scenario.

Real-world impact: in our skill matrix, agents that pass every other test still fail governance_denied scenarios because they never wire checkGovernance() against registered governance agents. The rule was never visible to them.

Proposal

Add compliance/universal/governance.yaml with the following normative shape:

id: universal/governance
title: Governance Consultation
applies_to: any mutating tool on accounts that have registered governance agents
description: |
  When an account has registered governance agents (via sync_governance or sync_accounts),
  every mutating request against that account MUST consult the registered governance agent(s)
  before performing the mutation. If the governance agent returns status 'denied',
  the request MUST be rejected with error code GOVERNANCE_DENIED, with `findings` propagated
  verbatim from the governance agent's response.

normative_requirements:
  - mutating tools (per MUTATING_TASKS): create_media_buy, update_media_buy,
    sync_creatives, acquire_rights, activate_signal, log_event, ...
  - registration source: sync_governance OR sync_accounts.governance_agents[]
  - check via: checkGovernance() helper from @adcp/client (or equivalent)
  - on denial: return adcpError('GOVERNANCE_DENIED', { findings: plan.findings })
  - on conditions: implementations MAY apply conditions or deny in strict mode
  - on approved: proceed with mutation

scenarios:
  - happy_path_no_governance: account has no registered governance agents → mutation proceeds normally
  - approved: governance returns 'approved' → mutation proceeds, governance_context echoed in response
  - conditions: governance returns 'conditions' → mutation MAY proceed with conditions attached, OR MAY deny
  - denied: governance returns 'denied' → mutation rejected with GOVERNANCE_DENIED + findings

cross_references:
  - protocol-wide block in 3.0 GA preamble (already names idempotency, signed-requests; should also name governance consultation)
  - check_governance request/response schema
  - sync_governance / sync_accounts.governance_agents[] registration flow

Mirror the structure of universal/idempotency.yaml so the conformance runner already knows how to grade it. Add a baseline check: every mutating-tool storyboard step picks up an additional implicit assertion ("if this account has registered governance agents in the seed fixture, the agent must have called check_governance before responding").

Protocol-wide block update

The 3.0 GA preamble lists:

Two requirements apply to every mutating AdCP operation regardless of specialism:

• idempotency_key ...
• RFC 9421 HTTP Signatures ...

Add a third bullet:

• Governance consultation — if the account has registered governance agents, the implementation MUST consult them before performing the mutation. See universal/governance.yaml for the normative obligation. Optional only when no governance agents are registered.

Files affected

• compliance/universal/governance.yaml (new file, modeled on idempotency.yaml)
• docs/v3/protocol/protocol-wide-requirements.md (add bullet)
• llms.txt (add cross-reference under each mutating tool's "see also" section)
• Specialism storyboards that already test the obligation get a references: [universal/governance] annotation so it's machine-discoverable.

Source

Surfaced during AdCP @adcp/client skill matrix runs. Out of 8 storyboard pairs tested across multiple cycles, every implementation that wires governance does so by accident (after copying from a worked example) rather than by reading a normative requirement. Confirmed by protocol expert review with grade C+ for "cross-cutting obligation discoverability" (idempotency exemplary; governance scattered or implicit).

[bokelley]

Part of #3090 (epic — AdCP 3.x spec drift bundle).

[bokelley]

Triage

Classification: Feature request (new compliance artifact)
Bucket(s): compliance-suite, spec/protocol (no spec/protocol label exists — noted in run summary)
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: two blockers — proposed YAML shape (normative_requirements/scenarios top-level keys) does not match the phases/steps/validations structure the conformance runner parses; multi-agent pre-wiring (sync_governance registration, governance agent at $context.governance_agent_url) is absent from the spec, making the denied/conditions scenarios non-executable. Also: no named capability key in get_adcp_capabilities for the runner's not_applicable skip path.
• adtech-product-expert: two blockers — without a capability-gating model (analogous to request_signing.supported: true), a universal storyboard is de facto breaking for existing loose governance-aware-seller implementations; governance storyboard remediation (governance_aware_seller storyboard fails with __no_phases__ error #2972, fix(compliance): add capability_discovery phase to governance_aware_seller #2973) must stabilize before a new normative universal surface is layered on top. Also: idempotency analogy is structurally wrong — idempotency is single-agent and unconditional; governance is three-party and account-configuration-conditional.

My take: The discoverability gap is real and the direction is right. Two design decisions need your call before this can execute: the capability-gating model and the ship target.

Option A — capability-gated universal storyboard (mirrors signed-requests 3.1 reclassification):

# compliance/universal/governance.yaml — schematic
id: universal/governance
category: core
capability_gate:
  path: "adcp.governance_consultation.supported"
  value: true
  skip_result: not_applicable   # sellers without the flag grade not_applicable, not failed
phases:
  - id: governance_plan_setup   # sync_plans on governance agent (delegates to existing scenario step)
  - id: seller_setup            # sync_governance registration
  - id: consultation_behaviors  # approved / conditions / denied — full phases/steps/validations
prerequisites:
  test_kit: "test-kits/acme-outdoor.yaml"

Sellers add adcp.governance_consultation.supported: true to get_adcp_capabilities. No breaking change for sellers that don't claim it. Requires new get_adcp_capabilities key and full phases/steps authoring. Target: 3.2, after #2972/#2973 close.

Option B — prose normative document + references annotations (no new runner surface):

# compliance/universal/governance-normative.yaml
id: universal/governance-normative
category: core
normative: true    # runner skips grading; used only as a cross-reference anchor
title: "Governance consultation — cross-cutting normative obligation"
description: |
  When an account has registered governance agents (via sync_governance or
  sync_accounts.governance_agents[]), every mutating request MUST consult
  them before performing the mutation. ...

# Added to existing governance storyboards:
references: [universal/governance-normative]

Low execution risk. Existing storyboards gain machine-discoverable references. Fixes discoverability without touching the runner's grading surface. Ships in 3.1 alongside #2972/#2973 remediation. Does not solve the "runner can prove it" problem — only the "implementer can find it" problem.

---

@bokelley, your call: Option A (full capability-gated storyboard with phases/steps, ship in 3.2 post-remediation) or Option B (prose normative + references annotation, ship in 3.1 with remediation)? If A, the open design question is whether adcp.governance_consultation.supported is the right capability key name or whether it should compose with the existing governance_aware capability flag.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_017wkdkehsPTRy77XffcPPVd

---

Generated by Claude Code

[bokelley]

Direction confirmed: the cross-cutting governance obligation is real and the discoverability gap is what we want to close. The expert blockers aren't on the concept — they're on the execution shape.

Going with Option A from the triage: capability-gated universal storyboard, ship in 3.2 after #2972/#2973 remediation closes. Concrete design constraints to honor when the implementation lands:

1. YAML shape must match the runner parser — phases / steps / validations (not normative_requirements / scenarios from this issue body). The runner needs to actually grade it.
2. Capability-gated — new adcp.governance_consultation.supported: true on get_adcp_capabilities. Sellers without the flag grade not_applicable, not failed. Mirrors the signed-requests 3.1 reclassification pattern. Open sub-question: whether this composes with the existing governance_aware capability flag or stands alone — defer to implementation.
3. Multi-agent pre-wiring is in scope — sync_governance registration + governance agent at $context.governance_agent_url need to be set up in prerequisites before the consultation phase runs. The denied / conditions / approved scenarios are non-executable without this.
4. Idempotency analogy is structurally wrong — idempotency is single-agent and unconditional; governance is three-party and account-configuration-conditional. Frame the doc accordingly: cross-cutting conditional obligation, not unconditional.
5. Blocks on governance_aware_seller storyboard fails with __no_phases__ error #2972 / fix(compliance): add capability_discovery phase to governance_aware_seller #2973 stabilizing — don't layer a new normative universal surface until governance remediation has settled.

Dropping needs-wg-review — not a working-group call, this is a maintainer-driven implementation issue with a clear shape. Will reopen for WG ratification only if the capability key naming turns into a contested call.

[sangilish]

I can help with a first implementation-prep slice here before any new universal storyboard PR:

1. inventory the existing governance consultation coverage across current storyboards (governance_denied, sync_governance setup, governance_context echo, findings propagation),
2. identify which pieces can be reused as prerequisites/steps for a capability-gated universal/governance scenario,
3. call out gaps that still depend on governance_aware_seller storyboard fails with __no_phases__ error #2972/fix(compliance): add capability_discovery phase to governance_aware_seller #2973 or capability-key naming,
4. keep the output as an issue comment / short doc first, not a runner behavior change.

That should make the eventual 3.2 implementation smaller and avoid turning the first slice into a new normative surface before the remediation blockers are settled.

[bokelley]

Yes, please go ahead with the implementation-prep inventory.

Keep this as an issue comment or short doc first, not a runner behavior change. The useful output is a matrix of existing coverage, reusable steps/validations, and remaining gaps for a future capability-gated universal/governance scenario.

One update: #2972 is closed and #2973 is merged, so treat those as remediation to verify rather than active blockers. Remaining open questions are capability-key naming, runner skip semantics, and which existing scenario pieces can be composed safely.

[bokelley]

Implementation-prep inventory — universal/governance capability-gated storyboard

Here's the matrix of existing coverage, reusable phases, and gaps. No runner behavior changes; this is a reference doc for the 3.2 authoring sprint.

---

Existing governance consultation coverage

Behavior covered	File	Phase / step	Task	Validation anchors
sync_plans (strict plan)	governance-spend-authority/denied.yaml	plan_registration.sync_plans	sync_plans	response_schema, plan_id present
sync_plans (conditional policies)	governance-spend-authority/index.yaml	plan_registration.sync_plans	sync_plans	response_schema, plan_id present, version present
sync_accounts + sync_governance registration	brand-rights/scenarios/governance_denied.yaml	brand_agent_setup	sync_accounts, sync_governance	response_schema, account_id present
sync_governance maxItems:1 rejection	governance-aware-seller/scenarios/governance_multi_agent_rejected.yaml	multi_agent_rejected.sync_governance_two_agents	sync_governance	error_code INVALID_REQUEST or VALIDATION_ERROR
check_governance → approved	governance-spend-authority/index.yaml	governance_check_conditions	check_governance	verdict, governance_context
check_governance → approved_with_conditions	governance-spend-authority/index.yaml	governance_check_conditions	check_governance	verdict, conditions, governance_context
check_governance → denied	governance-spend-authority/denied.yaml	governance_check.check_governance_denied	check_governance	verdict: denied, findings
check_governance → delivery drift re-eval	governance-delivery-monitor/index.yaml	drift_recheck.check_governance_drift	check_governance	verdict, findings
create_media_buy with governance_context echo	governance-spend-authority/index.yaml	create_buy_with_conditions.create_media_buy	create_media_buy	response_schema
acquire_rights denied via structured rejection arm	brand-rights/scenarios/governance_denied.yaml	rights_denied.acquire_rights_denied	acquire_rights	rights_status: rejected, reason, no dual errors[]
Cross-step: denial blocks mutation	governance-aware-seller, governance-spend-authority, governance-delivery-monitor	invariants: root field	—	governance.denial_blocks_mutation, status.monotonic

---

Reusable phases for universal/governance

Phase 1 — governance_plan_setup
Source: brand-rights/scenarios/governance_denied.yaml §governance_plan_setup or governance-spend-authority/denied.yaml §plan_registration
Changes needed: swap comply_scenario value to universal_governance; parametrize plan_id. Zero risk.

Phase 2 — seller_setup
Source: brand-rights/scenarios/governance_denied.yaml §brand_agent_setup (sync_accounts + sync_governance)
Changes needed: comply_scenario, parametric account. Uses $context.governance_agent_url already. Zero risk.

Phase 3a — consultation_approved
Source: governance-spend-authority/index.yaml §governance_check_conditions + §create_buy_with_conditions
Steps: check_governance (decision: approved) → create_media_buy with governance_context
Changes needed: new task payload, comply_scenario: universal_governance. Low risk.

Phase 3b — consultation_conditions
Source: governance-spend-authority/index.yaml §governance_check_conditions
Same as 3a but verdict path stays on conditions branch. Validated in existing storyboard. Low risk.

Phase 3c — consultation_denied
Source: governance-spend-authority/denied.yaml §governance_check.check_governance_denied for the check_governance step; seller propagation (GOVERNANCE_DENIED in errors[]) comes from governance-aware-seller/requires_scenarios: media_buy_seller/governance_denied
Composition note: create_media_buy denial uses GOVERNANCE_DENIED in errors[] (top-level error envelope), not the structured rejection arm that acquire_rights uses. These are two distinct wire-placement patterns — don't conflate them when composing Phase 3c.

Invariants
governance.denial_blocks_mutation and status.monotonic are already defined and can be copied verbatim to the universal storyboard root. No new invariant authoring needed.

---

Gaps — new work required

1. New schema field (non-breaking additive)
get-adcp-capabilities-response.json → governance properties block currently has only aggregation_window_days, property_features, creative_features. Need to add the consultation-capability flag (see open question 1 below). One field addition, no downstream breakage.

2. requires_capability gate
storyboard-schema.yaml line 246 already defines this field:

requires_capability:
  path: "governance.consultation_supported"   # pending naming decision
  equals: true
  # skip_result.reason: not_applicable emitted automatically

No runner changes needed. The gate works identically to the compliance_testing capability gate. The only token is the field name (open question 1).

3. happy_path_no_governance phase (no existing coverage)
Account with no registered governance agents → mutation proceeds normally. Required to prove the conditional gate. Steps: sync_accounts (omit sync_governance) → create_media_buy → succeeds. No existing scenario covers this path.

4. references: cross-annotation on 5 existing storyboards
references: is not currently defined in storyboard-schema.yaml (verified). Before annotating existing files, need to decide whether to add this field to the schema or use an inline $comment annotation instead. The 5 target files are:

• governance-aware-seller/index.yaml
• governance-spend-authority/index.yaml
• governance-spend-authority/denied.yaml
• governance-delivery-monitor/index.yaml
• brand-rights/scenarios/governance_denied.yaml

---

Open questions (unchanged from prior triage + your May 1 direction)

1. Capability key naming — two viable options:

Option A — nested inside existing governance block (mirrors aggregation_window_days):

// get-adcp-capabilities-response.json governance properties
"consultation_supported": {
  "type": "boolean",
  "description": "Agent evaluates check_governance on mutating requests for accounts with registered governance agents."
}
// gate path: "governance.consultation_supported"

Option B — new top-level block (mirrors request_signing.supported):

"governance_consultation": {
  "type": "object",
  "properties": {
    "supported": { "type": "boolean" }
  }
}
// gate path: "governance_consultation.supported"

Both are non-breaking additive. Option A adds less schema surface; Option B gives a cleaner capability-block pattern for future extensions (e.g., governance_consultation.strict_mode). Either works with the existing requires_capability gate.

2. Runner skip semantics — already solved: requires_capability in storyboard-schema.yaml emits skip_result.reason: not_applicable automatically. No runner changes needed for either naming option.

3. Safe-to-compose pieces — summary:

• ✅ Phases 1, 2, 3a, 3b: composable as-is with comply_scenario swap
• ⚠️ Phase 3c (consultation_denied): composable for the check_governance step; seller-side GOVERNANCE_DENIED propagation needs media_buy_seller/governance_denied scenario referenced via requires_scenarios
• ✅ Invariants: copy verbatim
• ❌ happy_path_no_governance: new authoring required
• ❓ references:: needs schema field decision first

---

Once the capability key name is decided, the implementation delta is: one schema field addition + one new YAML storyboard (~150 lines) composing the phases above + references: annotations on 5 files (if the field is added to the schema). Estimated as a 3–4 file PR.

Session: https://claude.ai/code/cse_0171KwgXTtwtgduow7BxXqcx

---

Generated by Claude Code