Skip to content

Governance: campaign-governance coherence sweep — 8 page-vs-spec conflicts, 2 spec-vs-schema contradictions, 6 undefined behaviours #8733

Closed

Description

@lukasz-pubx

Status (updated 2026-11-18): complete

The Governance working group reviewed this issue on a call on 2026-11-10. It accepted every recommendation except C5, which it left open. A4 was decided against the original recommendation. On 2026-11-11 the work was split into three pull requests (split), and the C5 key was settled as (owner_principal, seller_agent) (acceptance, correction). On 2026-11-13 the three questions that were still open were answered (reply): C5 stays in #8931 and ships in 3.3, A4 is the denied verdict as the working group decided, and the default removal goes in PR 3. On 2026-11-15 two of the picks, A4 for delegation failures and C1, were revised to match the uniform-response rule (decision record). All four pull requests are merged, the last one on 2026-11-18. The three questions that this issue leaves undecided are in #9083. This description has been updated in place so that it is the single current statement of what was decided and done; the two comments below record how the decisions were reached (feedback and corrections, call outcome).

Item Decision Change
A1 Reject the sync with VALIDATION_ERROR; the previous plan stays in force Doc + reference agent
A2 Mode is agent configuration, not a plan field Doc
A3 Checks do not reserve budget; "reserve" keeps one meaning Doc
A4 denied verdict, in every governance mode, for an authenticated caller that can access the plan and fails approved_sellers or delegations. A caller that cannot access the plan gets PLAN_NOT_FOUND. PERMISSION_DENIED only for an authentication or credential failure, which includes a governance_context that is expired, fails verification or was issued for another plan Doc (three pages) + reference agent
A5 verdict, not status Doc
A6 A re-sync does not re-validate active buys Doc
A7 The delivery outcome example is buyer-called Doc
A8 Schema vocabulary (escalations[], escalation_rate) Doc
A9 Examples self-consistent; index table carries the note Doc
B1 The human-review MUST applies in every mode Doc + enum description
B2 Omission accepted, explicit false rejected; "default": false removed Schema (compatible) + doc
B3 Restrict or mark the legacy response branch Schema description
C1 Unique per owner principal. Another principal's sync_plans with the same ID creates or updates that principal's own plan. A check_governance caller that can access more than one plan with the ID it sends gets VALIDATION_ERROR Doc + the plan_id description
C2 execute_only acts only on bindings that already hold an approved intent Doc + enum description
C3 No geography, or country level only, is outside a regions-restricted plan Doc
C4 Four sync_plans validation rules as proposed Doc + x-adcp-validation
C5 The key is (owner_principal, seller_agent). Whether buyer-side thresholds also sum across sellers is a separate question, now in #9083 Doc + one schema description; changes behaviour for an agent keyed on a derived account

Pull requests:

What changed in this description on 2026-11-18: this status section and the pull request list; the A4 and C1 rows of the table; a note under A4, C1 and C2 that records what merged; the two undecided C5 points moved to #9083; one sentence in Compatibility; a result under each acceptance criterion; Related. The evidence quotes and the decisions recorded on 2026-11-10 are left as they were.

What changed in this description on 2026-11-10: A4 rewritten for the reversed decision; B2 extended with the schema default; C5 rewritten as an open question and reclassified from doc-only to normative; a decision line added under every other item; Compatibility, Files affected, Acceptance criteria and Related updated to match. The evidence quotes are unchanged.

What changed in this description on 2026-11-14: the pull request list; the 2026-11-13 answers; a note under A4, C1 and C2 where PR 2 departs from the accepted wording; the C5 placement. The decisions recorded on 2026-11-10 are left as they were recorded.

What changed on 2026-11-11: this status section; C5 rewritten for the accepted key and for a corrected account of where account_id came from; the pull-request list added; the C5 lines in Compatibility, Files affected, Acceptance criteria and Related updated to match. No other item changed.

Summary

The campaign-governance doc set (docs/governance/campaign/**) disagrees with itself in a way an implementer cannot resolve by reading harder. As of ded86cd (3.3.0-beta.4; the same text is live in the 3.2.8 build), the task pages, audit-trail.mdx and safety-model.mdx contradict specification.mdx in 8 places, the specification contradicts its own schemas in 2 places, and 6 behaviours that every governance agent must implement are undefined. This issue asks for a coherence sweep in the style of #8077: one page owns each rule, the others defer to it, and the undefined behaviours get a one-sentence normative answer each. Every claim below was re-verified against the pinned tree; items that were already fixed on main are listed at the end so triage does not re-litigate them.

Line numbers are into the pinned tree at ded86cd94361f0e4eb88ac21e5e7be67f00106d7 and should be re-verified at implementation time. Re-checked on 2026-11-10 at 13092c2: every file cited in this issue is identical to the pinned tree, so the line numbers still hold.

Part A — pages that contradict the specification

For each item: the two passages, which one I recommend wins, the edit, and the working-group decision. Unless stated otherwise the fix is doc-only and the surviving rule is normative (it already is on one of the two pages).

A1. Budget reduced below committed spend: reject the sync, or accept and flag?

  • docs/governance/campaign/tasks/sync_plans.mdx:291 — VALIDATION_ERROR … "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." and :166 "A rejected sync leaves the plan unchanged."
  • docs/governance/campaign/specification.mdx:620 — "If an amendment reduces the budget below the currently committed amount, the governance agent flags this as a finding on the next governance check."

Two conformant agents: one returns VALIDATION_ERROR and keeps the old plan; the other bumps the version, hashes a plan whose budget.total is below committedBudget, and lets the next check_governance compute negative headroom. The reference agent already holds both readings: it rejects a period amount cut at sync time (server/src/training-agent/governance-budget-periods.ts:317), accepts a budget.total cut and surfaces it later as a budget_authority warning finding at outcome time (server/src/training-agent/governance-handlers.ts:3326-3331), while its comment at governance-handlers.ts:1214-1215 asserts the "same VALIDATION_ERROR as a budget.total that drops below committed spend" exists. Recommend the task page wins (reject): #7965 chose reject for periods, and a plan whose total is below its commitments has no usable headroom. Edit: replace the specification.mdx:620 sentence with "A sync that reduces budget.total (or a period amount) below the amount already committed is rejected with VALIDATION_ERROR and leaves the plan unchanged.", and add the missing sync-time check to the reference agent.

Decided (WG call, 2026-11-10): accepted as recommended. The previous plan stays in force, so the campaign keeps running. Reducing spend that is already committed is settled with the seller, not through a plan re-sync.

A2. Where governance mode lives

  • docs/governance/campaign/audit-trail.mdx:233 — "mode is set on the plan via [sync_plans] and is the operator's primary lever." and :316 "A plan can shift modes between revisions".
  • docs/governance/campaign/specification.mdx:876 — "Governance mode (audit, advisory, enforce) is an internal implementation detail of the governance agent, not a protocol-level field." and :883 "Mode is configured by the buyer's policy team on the governance agent itself, not via the protocol."; tasks/check_governance.mdx:728 and tasks/get_plan_audit_logs.mdx:326 — "not from a plan field".
  • static/schemas/source/governance/sync-plans-request.json has no mode property; mode exists only response-side (check-governance-response.json:291, get-plan-audit-logs-response.json:311) and enums/governance-mode.json describes it as "Operating mode for a governance agent."

Specification and schema win. Edit audit-trail.mdx:233 and :316 to say mode is agent configuration recorded on each check entry, and that a mode change between two entries reflects a configuration change, not a plan revision.

Decided (WG call, 2026-11-10): accepted as written.

A3. Budget reservation and the word "reserve"

  • docs/governance/campaign/safety-model.mdx:78 — "Concurrent media buys are handled through optimistic concurrency control or budget reservation, preventing concurrent approvals that together exceed the plan budget."
  • docs/governance/campaign/specification.mdx:567 — "Budget checks are point-in-time: check_governance validates against the current committed total but does not reserve budget. If multiple agents execute concurrently against the same plan, two checks could both pass and the combined outcomes could exceed the authorized budget." (repeated at :391).
  • The specification also uses "reserve" in a ledger sense: :563 "governance conservatively reserves $150K and records the $120K report as a discrepancy"; tasks/report_plan_outcome.mdx:70 "the intent reserves the buyer-proposed positive-delta ceiling".

The safety-model page promises a property the specification explicitly disclaims. Specification wins. Edit safety-model.mdx:78 to state the point-in-time limitation and that concurrency control is a deployment concern (matching the "Human controls" and "Monitoring" operational non-goals in docs/reference/known-limitations.mdx:110-111). Separately, pick one verb: use "reserve" only for the intent-ceiling ledger entry, or rename that to "records the ceiling", so "does not reserve budget" cannot be read as contradicting :563.

Decided (WG call, 2026-11-10): accepted as written.

A4. Unapproved seller: error or denied verdict?

  • docs/governance/campaign/tasks/check_governance.mdx:744 — PERMISSION_DENIED … "the target/executing service is not authorized by approved_sellers."
  • docs/governance/campaign/audit-trail.mdx:179-202 — "A different seller calls check_governance and gets denied:" with "verdict": "denied", "category_id": "seller_compliance", "Caller https://ads.seller-rogue.example is not in the plan's approved sellers list.", and :202 "the audit entry captures the denied attempt through check_id."
  • docs/governance/campaign/specification.mdx:215 — "approved_sellers is evaluated against the target service that becomes the token aud, never against that buyer" — the audit-trail example evaluates it against the caller.

An error has no check_id and no audit check entry; a denied verdict has both. Auditors reading get_plan_audit_logs from two agents will see the rogue-seller attempt in one log and not the other.

Decided (WG call, 2026-11-10): the verdict shape wins. This reverses the original recommendation in this issue, which was PERMISSION_DENIED. The reason given: a rejected attempt by an unapproved seller must appear in the audit log.

  1. An authenticated caller that fails the approved_sellers evaluation receives verdict: "denied" with a seller_compliance finding and a check_id. This covers three cases: an intent check whose target is not in approved_sellers; an execution check whose authenticated caller is not the audience preserved from the approved intent; and an execution check whose caller has since been removed from approved_sellers.
  2. Delegation failures are treated the same way. An authenticated buyer-side caller that is neither the plan owner nor covered by a current entry in delegations receives denied with a delegation_authority finding.
  3. PERMISSION_DENIED remains only where there is no trustworthy identity to record: the caller is unauthenticated, or the authenticated identity does not match the declared caller. These produce no check_id and no plan-scoped audit entry, so a party with no established identity cannot append to another principal's audit log.

PR 2 (#9006) adds one sentence to this decision. The specification says an agent in audit mode always returns approved, and nothing said whether mode applies to an authority failure. PR 2 states that mode governs how findings about the governed action are enforced and does not relax who may call. So an execution caller that is not the preserved audience, and a buyer-side caller outside delegations, are denied in every mode. A finding about the target seller on an intent check still follows mode. One limit applies to point 2: a caller with no access to the plan at all receives PLAN_NOT_FOUND, the same as for an unknown plan_id, because the PLAN_NOT_FOUND definition forbids telling the two apart. This limit was first drafted for PR 4 (#9015) and moved to PR 2.

Revised on 2026-11-15 and merged in #9006 (decision record). Point 2 now applies only to a caller that can access the plan. A plan is accessible to its owner principal, to an agent named in a delegations entry that has not expired, and to a caller that presents a governance_context or consultation_context that the governance agent issued for that plan. Any other caller gets PLAN_NOT_FOUND, exactly as for a plan_id that does not exist, and the attempt writes no audit entry. Point 3 stands, and PERMISSION_DENIED also covers a presented governance_context that is expired, fails verification or was issued for another plan. The governance agent verifies a presented context before it resolves plan access.

Edits:

  • tasks/check_governance.mdx:744 — narrow the row to "Authenticated identity is missing or does not match the declared caller."
  • specification.mdx:215 — add one sentence: a failed approved_sellers or delegations evaluation for an authenticated caller is returned as a denied verdict with a finding, never as an error.
  • audit-trail.mdx:179-202 — the example labels a seller's call "check_type": "intent" (:186, repeated at :242, :265, :290). Under specification.mdx:215 a seller calls execution checks, and on an intent check approved_sellers is evaluated against the target, "never against that buyer". The example becomes an execution check.
  • Reference agent — it already returns the finding for an unapproved seller (server/src/training-agent/governance-handlers.ts:2072-2083) and already errors on a missing or mismatched identity (:1866-1870, :1515-1522). Two gates return PERMISSION_DENIED where the decision now calls for a verdict: an authenticated execution caller that is not the preserved audience (:1727-1742), and a buyer-side caller that is neither owner nor delegate (:1895-1903), which returns before the delegation_authority finding at :2048-2070 can fire. In both, the error stays only for the unauthenticated case.
  • enums/error-code.json:215 is generic across tasks and needs no change.

A5. plans[].entries[].status versus verdict

  • docs/governance/campaign/tasks/get_plan_audit_logs.mdx:324 — "| plans[].entries[].status | enum | Governance check status (present for check entries). |"
  • Every example on the page (:164, :180) and audit-trail.mdx:50 use verdict; static/schemas/source/governance/get-plan-audit-logs-response.json:299-301 defines verdict ("Renamed from status in 3.1 alongside check-governance-response for vocabulary consistency") and the entries object has no status property.

Schema wins; rename the table row. Doc-only.

Decided (WG call, 2026-11-10): accepted as written.

A6. Does a re-sync re-evaluate active campaigns?

  • docs/governance/campaign/tasks/sync_plans.mdx:112 — "Syncing a plan that already exists (same plan_id) updates it. The governance agent increments the version and re-evaluates any active campaigns against the updated rules."
  • docs/governance/campaign/specification.mdx:620 — "Active media buys that were approved under the previous plan version are not automatically re-validated -- the governance agent evaluates them against the updated plan on the next check_governance call (e.g., the next delivery check)."

Specification wins. Edit sync_plans.mdx:112 to "… increments the version. Active media buys are not re-validated until their next check_governance call."

Decided (WG call, 2026-11-10): accepted as written.

A7. A seller-called delivery outcome in the audit example

  • docs/governance/campaign/tasks/report_plan_outcome.mdx:16 — "Sellers do not call this task. They report delivery data via [check_governance] with phase: "delivery"."
  • docs/governance/campaign/tasks/get_plan_audit_logs.mdx:204-218 — entry "id": "out_del_001", "type": "outcome", "caller": "https://ads.seller-example.com/adcp", … "outcome": "delivery".
  • get_plan_audit_logs.mdx:341 — "plans[].entries[].delivery … Buyer-attributed observation retained on a delivery outcome. It never overwrites the seller statement."

The example contradicts the page's own table and the task page. Change the example's caller to the buyer agent (the seller statement is the preceding check entry with phase: "delivery"). Doc-only.

Decided (WG call, 2026-11-10): accepted as written.

A8. Three vocabularies for the same drift metrics

  • docs/governance/campaign/specification.mdx:578,592,607,616 — human_review_rate, human_review_rate_min.
  • docs/governance/campaign/tasks/get_plan_audit_logs.mdx:134,143,301,307 — escalations[], escalation_rate.
  • docs/governance/campaign/audit-trail.mdx:44,99,101 — summary.human_reviews[], human_review_rate, human_review_rate_min.
  • static/schemas/source/governance/get-plan-audit-logs-response.json:155-246 defines escalations, drift_metrics.escalation_rate, escalation_rate_trend, auto_approval_rate, human_override_rate, mean_confidence, thresholds.{escalation_rate_max, escalation_rate_min, auto_approval_rate_max, human_override_rate_max}. The only human_review* token in the schema is the statuses.human_reviewed count (:144). human_reviews, human_review_rate and human_review_rate_min exist in no schema.

A buyer following the specification's "set human_review_rate_min" guidance has no field to set it in. Schema wins: rewrite the specification and audit-trail passages in the schema's vocabulary (escalations[], escalation_rate, thresholds.escalation_rate_min) and state in one sentence that statuses.human_reviewed counts the resolved escalations. No schema change. Alternative: add human_review_rate to the schema as an alias — rejected here because two names for one number is the defect being fixed.

Decided (WG call, 2026-11-10): accepted as written.

A9. Finding category labels (editorial)

The same geo violation is labelled strategic_alignment in findings (tasks/check_governance.mdx:602,648; specification.mdx:1135) while categories_evaluated on the same page lists geo_compliance (:496), and index.mdx:195 presents a six-row category table without the "agent-internal, not a protocol enum" note that tasks/sync_plans.mdx:232 and check-governance-response.json:151-153 carry. No schema constrains these values, so this is not a conformance conflict, but the examples should be self-consistent and the index table should carry the same note. Doc-only, lowest priority in this issue.

Decided (WG call, 2026-11-10): accepted as written.

Part B — the specification contradicts its own schemas

B1. Audit mode "always returns approved" versus the human-review MUST

  • docs/governance/campaign/specification.mdx:879 — "A governance agent in audit mode internally always returns approved with findings attached"; enums/governance-mode.json:14 — "audit": "Log all checks, never block. Findings are recorded but the governance agent always returns approved."
  • specification.mdx:156 — "When human_review_required is true, the governance agent MUST escalate any action on the plan for human review before execution — regardless of the plan's reallocation_threshold."; sync-plans-request.json:294 — same MUST.

An agent in audit mode holding a fair_housing plan cannot satisfy both sentences. The MUST exists because of Art 22 / Annex III (#2310); it should not be defeatable by a configuration knob the protocol does not even see. Recommend: the human-review MUST is mode-independent. Edit :879 and the enum description to "… always returns approved with findings attached, except for plans with human_review_required: true, which escalate in every mode." Alternative: audit-mode agents reject sync_plans for such plans with VALIDATION_ERROR — workable but leaks mode into the protocol, which A2 says it must not. Normative; doc + enum-description only.

Decided (WG call, 2026-11-10): accepted as recommended. The human-review MUST applies in every mode; a mode setting must not be able to switch off a legal requirement.

B2. human_review_required "set automatically" versus a schema that rejects its omission

  • specification.mdx:154 — "The governance agent sets human_review_required: true automatically when any resolved policy or policy_category on the plan carries requires_human_review: true."; :165 — "… overrides a caller-supplied false when a triggering policy is present."
  • static/schemas/source/governance/sync-plans-request.json:447-456 — "then": { "properties": { "human_review_required": { "const": true } }, "required": ["human_review_required"] } (both the four-category branch at :429-446 and the eu_ai_act_annex_iii branch at :459-481).

With the schema enforced, a plan that omits the flag is INVALID_REQUEST and a plan with false is INVALID_REQUEST, so neither sentence in the prose can ever execute. With the schema not enforced (a client that validates at the model layer only), the prose governs and the explicit-false case is silently rewritten. Two deployments diverge on the same request. Recommend: drop required from both then branches and keep const: true. Explicit false stays schema-rejected (preserving the #2310/#2338 invariant), omission is accepted and the agent sets the flag, and the prose at :154/:165 becomes true as written (change "overrides a caller-supplied false" to "rejects a caller-supplied false"). Schema change, compatible (widens acceptance). Also fix docs/reference/known-limitations.mdx:80, which describes this invariant as rejecting authority_level: agent_full, a field the current schema condition does not use.

Decided (WG call, 2026-11-10): accepted as recommended, with one addition raised after filing.

sync-plans-request.json:293 declares "default": false on human_review_required. Once omission is valid, that annotation works against the decision in two ways. A consumer that applies schema defaults turns a valid omitted field into an explicit false, which the then branches reject, so a valid request becomes an invalid one (reproduced in one SDK, adcontextprotocol/adcp-client-python#1852). It also sits badly with specification.mdx:917: "Governance agents MUST hash the plan as-supplied; they MUST NOT synthesize omitted optionals to default values and MUST NOT drop explicit nulls."

Additional edits: remove "default": false at :293 and say in the description that an omitted flag means the governance agent derives it; add one sentence at specification.mdx:917 that schema default annotations are never applied to the hash preimage. budget.accounting_mode at :60 keeps its "gross_commitment" default, which is semantically real. Both changes are compatible, because default is an annotation and changes no instance's validity. Minor, same area: vector 004b-human-review-explicit-null.json supplies null for a property typed "type": "boolean", so its plan_as_supplied is not schema-valid; a note in the vector that it exercises canonicalisation only would stop a validating harness from rejecting it.

B3. Residual: the legacy check_governance response branch still permits conditions on execution checks

check-governance-response.json:12-31 restricts conditions to check_type: "intent", and specification.mdx:876 says "execution checks return approved or denied", but the else branch for responses without check_type (:69-100) carries no phase restriction, and enums/governance-decision.json / governance-phase.json carry none either. Either add the restriction to the legacy branch or mark that branch as 3.0-compat in its description. Schema-description or x-adcp-validation change; compatible.

Decided (WG call, 2026-11-10): accepted as written.

Part C — behaviours every implementation must decide, undefined today

Each item below had zero hits for the relevant terms in docs/governance/** and static/schemas/source/governance/**. Proposed answers are normative and additive (no field changes unless stated).

C1. plan_id uniqueness namespace

Ownership is defined (check-governance-request.json:233 "A plan is owned by the authenticated buyer principal that synchronized it"; specification.mdx:342-343) but uniqueness is not: tasks/sync_plans.mdx:183 says only "Unique identifier for this plan." Whether two principals may each sync plan-q1-2026 is unstated, and the answer decides whether a sync_plans from a second principal creates a second plan or is an ownership violation. Propose: plan_id is unique per owner principal; a sync naming an existing plan_id from a different principal is rejected with PERMISSION_DENIED (never silently creates a sibling plan). One sentence in sync_plans.mdx and the plan_id description.

Decided (WG call, 2026-11-10): accepted as proposed. Read together, the two halves mean that a plan_id names at most one plan within a governance agent: the principal that first syncs it owns it, and a sync_plans from any other principal naming that id is rejected with PERMISSION_DENIED.

PR 2 (#9006) departs from this, and states a per-owner namespace. Two principals may each hold the same plan_id, and neither can read, change or learn of the other's plan. The reason is the PLAN_NOT_FOUND definition in enums/error-code.json: "never distinguish 'exists but unauthorized' from 'does not exist'". A PERMISSION_DENIED on reuse tells any authenticated principal that the ID exists, and lets one principal block another by syncing an ID first. The reference agent has namespaced plans per owner since #6214. This issue mentioned neither when it proposed C1.

Confirmed on 2026-11-15 and merged in #9006 (decision record), with one addition. Because the namespace is per owner, one caller can have access to more than one plan with the same ID, for example a delegate of two owners that chose the same ID. check_governance then returns VALIDATION_ERROR and evaluates the check against neither plan. Buyers SHOULD use globally unique plan IDs. #9077 proposes a way to name the plan owner in that case, for 3.4.

C2. What execute_only may initiate

specification.mdx:337 and enums/delegation-authority.json:14 — "Can execute pre-approved actions but cannot initiate new campaigns or reallocate budget." "Pre-approved" is undefined. Propose: a pre-approved action is one whose opaque action binding already holds an approved intent check in this plan's lifecycle; an execute_only delegate may run execution checks and accept_proposal for such bindings and may not initiate an intent check that would create a new binding or increase committed spend. One sentence in the delegations section and the enum description.

Decided (WG call, 2026-11-10): accepted as proposed.

PR 2 (#9006) is narrower than this. It keeps the definition of a pre-approved action and the prohibition. It does not say that an execute_only delegate may run execution checks, because the specification requires the caller of an execution check to be the seller that the approved intent named, and a delegate is a buyer-side agent.

Merged in #9006 in this narrower form, worded as an obligation on the governance agent: "The governance agent MUST deny an intent check from an execute_only delegate that would create a new binding or increase committed spend." The reference agent did not enforce it, which is #9075.

C3. Regions-restricted plans and requests with no (or country-level) geography

specification.mdx:487 — "A plan with regions: ["US-MA"] rejects actions not explicitly targeting Massachusetts, even if they are otherwise compliant."; sync-plans-request.json:248 — regions "restricts governed actions to these specific regions rather than the full country." Nothing says what a payload with no geographic targeting, or with countries: ["US"] only, is. Propose: such a payload is treated as targeting the whole country and is outside a regions-restricted plan; intent checks return conditions naming the region constraint, execution checks return denied. Doc-only.

Decided (WG call, 2026-11-10): accepted as proposed.

C4. Four small gaps on sync_plans validation

  1. Flight ordering — sync-plans-request.json:213-226 defines flight.start/end with no ordering rule. Propose end strictly after start → INVALID_REQUEST, mirroring the budget-period rule at tasks/sync_plans.mdx:289 ("overlapping or empty windows, a window outside flight").
  2. Duplicate ids — policy-entry.json:10 requires bespoke ids "unique within the authoring container" but policy_ids (:250-256) has no uniqueItems and nothing covers a custom_policies[].policy_id colliding with a registry id in policy_ids. Propose both → INVALID_REQUEST.
  3. Unresolvable registry policy id — the sync_plans error table (:289-291) has only INVALID_REQUEST, REFERENCE_NOT_FOUND (brand domain) and VALIDATION_ERROR (budget). Propose REFERENCE_NOT_FOUND with error.field pointing at the id, by precedent with the brand-domain row.
  4. "The same action" in the three re-call rule — tasks/check_governance.mdx:287 "SHOULD return denied after 3 unsuccessful intent re-calls for the same action" never says what "same" means, while :285 and check-governance-request.json:303 already bind consultation_context to principal, caller, plan, tool, purchase type and audience. Propose: "the same action" = re-checks carrying the same consultation_context.

Items 1 and 2 narrow what the schema accepts. For 3.x, state them in prose and as an x-adcp-validation annotation (the repo's mechanism for rules draft-07 cannot express); tightening the schema itself belongs at 4.0.

Decided (WG call, 2026-11-10): all four accepted as proposed.

C5. The trailing-window aggregation key names an account_id that no schema carries

specification.mdx:400 — "All plans attributable to the same (buyer_agent, seller_agent, account_id) tuple" (and :429) is a MUST-level anti-fragmentation rule, but no governance schema carries account_id (zero hits across static/schemas/source/governance/*.json), and tasks/get_plan_audit_logs.mdx:361 says tenant identity "is resolved from the submitted IDs".

Decided (2026-11-11): the key is (owner_principal, seller_agent). This is the original proposal of this item. The working group accepted it as a starting point on the 2026-11-10 call, the split comment placed it in PR 1, and it was accepted on the thread. The three-part key with brand that this description proposed on 2026-11-10 is withdrawn.

  • owner_principal is a defined term, not a wire field: the authenticated buyer principal that synchronized the plan.
  • Delegated sub-agents share the delegating buyer's aggregate, as :400 already says. The owner_principal element is the delegating principal, not the sub-agent's agent_url.
  • The change is in docs(governance): align campaign-governance pages with the specification and schemas #8931: specification.mdx:400, :421 and :429, and the governance.aggregation_window_days description at get-adcp-capabilities-response.json:3006, which named the old tuple too.

Correction to earlier versions of this item. They said that no governance schema carries account_id "since #6214". No governance schema has ever carried it: there are zero hits at v3.0.0, v3.1.0, v3.2.8 and on main. The third element of the key was always derived. The 3.0 and 3.1 request schemas said "the governance agent resolves account from the plan", and get-plan-audit-logs-request.json:21 on main still says "the governance agent resolves account from each plan". What #6214 changed was that wording in check-governance-request.json and report-plan-outcome-request.json, which now describe the plan as owned by the authenticated buyer that synchronized it.

The re-key changes behaviour for some agents. specification.mdx:421:

Governance agents MAY evaluate narrower aggregation scopes additionally (per-brand, per-campaign) but MUST NOT evaluate any scope broader than the declared window without operator sign-off. "Broader" covers both dimensions: a longer trailing window (time) and a wider key tuple (e.g., collapsing across account_id so two accounts share an aggregate).

Dropping the third element is the widening that sentence names, so :421 gets a different example in the same edit. Two consequences follow:

  • An agent that derives an account from the plan and partitions its aggregate by it satisfies the conformance example at :429-436 today. After the re-key it must aggregate across all of that principal's plans per seller, and may keep the per-account figure only as an additional, narrower scope.
  • A buyer principal that synchronizes plans for several advertisers pools their spend in one aggregate, so thresholds are reached earlier than under a per-account key.

For that reason #8931 asked maintainers to confirm where C5 belongs. Confirmed on 2026-11-13: C5 stays in #8931 and ships in 3.3, and the 3.2.x backport (#8980) leaves it out.

Moved to #9083 on 2026-11-18. These two points were still undecided when the pull requests merged:

  1. Do the buyer-side thresholds sum across the seller dimension or within it? The working group raised this on the call. The section names three thresholds: reallocation_threshold, human_review_required trigger points and registry-policy dollar floors. Its own example at :396 is a buyer splitting $999,900 into 100 buys of $9,999 to stay under a $10,000 human-review threshold. Summing within one seller leaves the same split across 100 sellers open, which would then need documenting as out of scope. Summing across sellers closes it, with limits defined per seller, such as budget.per_seller_max_pct (sync-plans-request.json:63-66), still summed within one seller.
  2. Two places docs(governance): align campaign-governance pages with the specification and schemas #8931 leaves alone, because each needs a decision and not an edit. get-plan-audit-logs-request.json:21 still says plans "uniquely scope account and operator". specification.mdx:440 says sellers also declare an aggregation window, and a seller cannot always tell a plan owner from its delegate.

C5 citations re-checked at 7ce107a.

Compatibility and migration

  • Doc-only on the surviving rule: A1–A3, A5–A9, B1, C1, C2, C3, C4.3, C4.4. Implementations that followed the losing page change behaviour; that is the point of the issue, and in every case the losing page was already contradicted by the specification or the schema.
  • Doc on three pages plus a behaviour change, no schema change: A4. An agent that returned PERMISSION_DENIED for an authenticated unapproved seller, or for a buyer-side caller outside delegations, now returns a denied verdict and writes an audit entry. Callers that branch on the error code for those cases must also handle the verdict. Only existing response fields are used. As merged, a caller that cannot access the plan at all gets PLAN_NOT_FOUND; the reference agent returned a denied verdict with a plan_lookup finding for that case before.
  • Schema, compatible: B2. Dropping required in both then branches widens acceptance; removing the default annotation changes no instance's validity.
  • Doc plus one schema description, with a behaviour change for some agents: C5. An agent that partitioned its aggregate by an account derived from the plan now aggregates across that principal's plans per seller, so aggregates get larger and thresholds are reached earlier. No wire field changes.
  • Schema-description / annotation, compatible: B3, C4.1, C4.2 (as x-adcp-validation; schema tightening deferred to 4.0).
  • Nothing here changes a wire field name, an enum member, or plan_hash canonicalization.

Files affected (as of ded86cd, identical at 13092c2; re-verify at implementation)

  • docs/governance/campaign/specification.mdx — A1, A3, A4 (:215), A6 (owner), A8, A9, B1, B2 (:154, :165, :917), C1–C4; C5 (:400, :421, :429)
  • docs/governance/campaign/audit-trail.mdx — A2, A4 (the example becomes an execution check), A8
  • docs/governance/campaign/safety-model.mdx — A3
  • docs/governance/campaign/tasks/sync_plans.mdx — A6, C1, C4
  • docs/governance/campaign/tasks/check_governance.mdx — A4 (the :744 row), A9, C4.4
  • docs/governance/campaign/tasks/get_plan_audit_logs.mdx — A5, A7
  • docs/governance/campaign/index.mdx — A9
  • docs/reference/known-limitations.mdx — B2 (field name)
  • static/schemas/source/governance/sync-plans-request.json — B2 (then branches; default at :293), C4 (descriptions / x-adcp-validation)
  • static/schemas/source/governance/check-governance-response.json — B3
  • static/schemas/source/protocol/get-adcp-capabilities-response.json — C5 (:3006, the aggregation_window_days description)
  • static/schemas/source/enums/governance-mode.json, delegation-authority.json — B1, C2 descriptions
  • server/src/training-agent/governance-handlers.ts — A1 (sync-time budget.total check), A4 (the gates at :1727-1742 and :1895-1903), B2 (set the flag on omission; the cascade at :374-384 already does this)
  • static/compliance/source/test-vectors/plan-hash/004b-human-review-explicit-null.json — B2 (a note only; the expected hash is unchanged)
  • Deliberately untouched: check-governance-request.json, report-plan-outcome-request.json, get-plan-audit-logs-response.json (the schemas win in A5 and A8), plan_hash canonicalization and every vector's expected hash, and the compliance storyboards — a grep of static/compliance/source for the losing phrases (re-evaluat, budget reservation, human_review_rate, human_reviews) hits only delivery-phase re-evaluation text, which the specification supports. No storyboard exercises an unapproved seller or an undelegated caller on check_governance today (approved_sellers appears under static/compliance/source only in a plan-hash vector), so A4 breaks no existing scenario; a scenario for it is worth adding.

Acceptance criteria

  1. For each of A1–A8 a single page states the rule and every other page either repeats it verbatim or links to it; grep for the losing phrase returns nothing.
  2. On check_governance, an authenticated caller that fails approved_sellers or delegations receives verdict: "denied" with a check_id, and the attempt appears in get_plan_audit_logs; an unauthenticated or mismatched caller receives PERMISSION_DENIED and leaves no entry. The training agent behaves this way.
  3. sync-plans-request.json accepts a regulated-category plan that omits human_review_required, rejects one that sets it false, and carries no default on the field; the training agent sets the flag on the omitted case.
  4. Each of C1–C4 is answered by one normative sentence in the page named above. For C5, specification.mdx:400, :421 and :429 state the key as (owner_principal, seller_agent); the cross-seller threshold question is answered in the same section or split into its own issue.
  5. docs/reference/known-limitations.mdx:80 names the field the schema actually constrains.

Result at 61a1638 (2026-11-18):

  1. Met. A search of docs/governance/, docs/reference/known-limitations.mdx and static/schemas/source/governance/ for the losing phrase of A1 to A6 and A8 returns nothing, and the A7 example names the buyer as the caller.
  2. Met, as revised on 2026-11-15. An unauthenticated or mismatched caller gets PERMISSION_DENIED. A caller that cannot access the plan gets PLAN_NOT_FOUND and leaves no entry. The training agent was changed to match in feat(governance): settle the campaign-governance rules that were contradictory or undefined #9006.
  3. Met. Both then branches carry const: true and no required, and the field has no default (fix(governance): accept an omitted human_review_required and state two sync_plans validation rules #9007).
  4. Met for C1 to C4 and for the C5 key. The cross-seller threshold question is split into Governance: decide whether aggregated-spend thresholds sum across sellers, and fix two statements left open by #8733 #9083.
  5. Met. The line names human_review_required.

Already resolved on main — listed so triage does not reopen them

These were real conflicts at 3.1.24 and are fixed in the pinned tree (and in 3.2.8): advisory-mode semantics (specification.mdx:880, safety-model.mdx:63, via #6214); the check_governance intent example now being a valid create_media_buy payload (tasks/check_governance.mdx:316-327, #6214); report_plan_outcome requiring check_id for every outcome with either the intent or the execution check accepted (report-plan-outcome-request.json:12-31, specification.mdx:235, #6214/#6305); execution checks being binary in the modern response shape (check-governance-response.json:12-31); credential binding by resolved agent URL plus owner principal instead of an undefined "account" (specification.mdx:872, #6214); and the modification delta model (specification.mdx:199).

Related

Activity

  1. added this to the Spec Backlog milestone on Nov 9, 2026
  2. added
    governanceIssue concerns the governance protocol domain
    documentationImprovements or additions to documentation
    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.
    on Nov 9, 2026
  3. lukasz-pubx commented on Nov 10, 2026

    @lukasz-pubx
    ContributorAuthor

    Update: working-group feedback so far, one reversal, one correction

    Re-verified at 8114430. None of the governance docs, schemas, vectors or reference-agent files cited in this issue has changed since ded86cd, so the line numbers above still hold. #8734 was fixed by #8781 in the meantime.

    The feedback below reached me outside this thread. I am recording it here so the resolutions sit in one place; anyone who gave it should correct me if I have it wrong.

    Item Feedback Effect on this issue
    A1 Reject with VALIDATION_ERROR. The previous plan stays in force, so the campaign keeps running. Reducing spend that is already committed is settled with the seller, not through a plan re-sync. As recommended.
    A4 Prefer a denied verdict to the error, so that a rejected attempt by an unapproved seller appears in the audit log. Reverses the recommendation. Details below.
    B1 The human-review MUST applies in every mode. A mode setting must not be able to switch off a legal requirement. As recommended.
    C1 Unique per owner principal; PERMISSION_DENIED when another principal reuses the id. As proposed.
    C5 (owner principal, seller agent) as a starting point, with an open question: does the seller belong in the key, given what the trailing-window limits are meant to protect? Open. Details below, including a correction to this issue.

    A4 as a denied verdict: three things the edit has to settle

    The audit-trail example (audit-trail.mdx:179-202) becomes the rule, and the PERMISSION_DENIED row at tasks/check_governance.mdx:744 narrows. That row currently covers three conditions in one sentence:

    Authenticated identity is missing/mismatched, the buyer-side caller is not authorized by delegations, or the target/executing service is not authorized by approved_sellers.

    1. Where the line between verdict and error sits. Proposed: a caller whose identity is missing or cannot be authenticated still receives PERMISSION_DENIED, with no check_id and no plan-scoped audit entry. An authenticated caller that fails the approved_sellers evaluation receives verdict: "denied" with a seller_compliance finding and a check_id. Without that floor, a party with no established identity can append entries to another principal's audit log.
    2. Whether delegation failures move with it. The audit argument is the same for a buyer-side agent outside delegations, and delegation_authority is already listed as an evaluated category in the examples (audit-trail.mdx:153, :190; tasks/check_governance.mdx:496). Recommend the same treatment: authenticated caller outside delegations gets denied with a delegation_authority finding. Either answer works, but the row should not leave the two cases split by accident.
    3. The surviving example must match the identity rule. specification.mdx:215: "On an execution check, the authenticated caller MUST equal the audience preserved from the approved intent, and that seller identity is evaluated against approved_sellers." On an intent check the same paragraph says approved_sellers is evaluated against the target service, "never against that buyer". The example labels a seller's call "check_type": "intent" (audit-trail.mdx:186, repeated at :242, :265, :290); it should be an execution check. The rule should also say that all three seller failures are verdicts: an intent whose target is not in approved_sellers, an execution check whose caller is not the preserved audience, and an execution check whose caller has since been removed from approved_sellers.

    Edits under this resolution: tasks/check_governance.mdx:744 (narrow the row to missing or unauthenticated identity), audit-trail.mdx:179-202 and its repeats (execution check), and one sentence at specification.mdx:215 stating that these evaluations produce a denied verdict. enums/error-code.json:215 needs a read to confirm its description still fits the narrowed use.

    C5: a correction to this issue, then the seller question

    Correction. C5 above describes the re-key as doc-only, "a definition of a term the MUST already depends on". That understates it. specification.mdx:421:

    Governance agents MAY evaluate narrower aggregation scopes additionally (per-brand, per-campaign) but MUST NOT evaluate any scope broader than the declared window without operator sign-off. "Broader" covers both dimensions: a longer trailing window (time) and a wider key tuple (e.g., collapsing across account_id so two accounts share an aggregate).

    Dropping account_id from the tuple is exactly the widening that sentence names. The re-key is still needed, because no governance schema has carried account_id since #6214 and an agent cannot key on a field it never receives. But :421 has to change in the same edit, and the change is normative: aggregates get larger and more commits cross a threshold. Please read the Compatibility section with C5 moved from "doc-only on the surviving rule" to "normative behaviour change".

    Does the seller belong in the key? The section states what it protects at specification.mdx:396:

    A buyer that fragments a $999,900 intended spend into 100 × $9,999 buys — each individually below an operator's $10,000 human-review threshold — would otherwise bypass review entirely.

    The thresholds it names are reallocation_threshold, human_review_required trigger points and registry-policy dollar floors. All three bound the buyer's own behaviour; none is a per-seller limit. With the seller in the key, the same $999,900 placed with 100 sellers at $9,999 each never aggregates. That is the argument :400 already makes for sub-agents: "otherwise the delegation surface itself reopens the fragmentation hole".

    One fact that may explain the seller element: :440 says "Sellers and governance agents declare their aggregation window". A seller-side evaluator sees only its own commits, so a per-seller aggregate is the most a seller can enforce. Only the governance agent sees across sellers.

    Options:

    1. The key follows the scope of the threshold (recommended). Thresholds that bound the buyer's own behaviour, which is all three named in this section, aggregate on the owner principal alone. A limit defined per seller aggregates on (owner principal, seller agent). :421 keeps its rule against silent widening, with a different example.
    2. (owner principal, seller agent) only. Smallest change from today's text. Cross-seller fragmentation stays open and should then be documented as out of scope.
    3. (owner principal, seller agent) as the MUST floor, owner-principal-only as a declared capability. Closest to :421 as written, which already allows a broader scope with operator sign-off. The cost is that buyers must check one more capability before relying on the defence.

    Any of the three resolves the issue. What cannot survive is a MUST keyed on a field no schema carries.

    Addendum to B2: the schema default

    static/schemas/source/governance/sync-plans-request.json:293 declares "default": false on human_review_required. If B2 is accepted as recommended (omission accepted, explicit false rejected on regulated plans), that annotation works against it in two ways:

    Proposed: remove "default": false at :293 and state in the description that an omitted flag means the governance agent derives it. budget.accounting_mode at :60 also carries a default ("gross_commitment"). That one is semantically real and can stay, with one sentence added at :917 that schema default annotations are never applied to the hash preimage. Both are compatible: default is an annotation and changes no instance's validity.

    Minor, same area: vector 004b-human-review-explicit-null.json supplies null for a property typed "type": "boolean", so its plan_as_supplied is not schema-valid. A note in the vector that it exercises canonicalisation only would prevent a validating harness from rejecting it.

    Citations re-verified against 8114430 with Claude Code assistance; re-verify at implementation time.

  4. lukasz-pubx commented on Nov 10, 2026

    @lukasz-pubx
    ContributorAuthor

    Update: working-group call, 2026-11-10

    Re-verified at 8114430; the cited files are unchanged.

    The working group reviewed the remaining questions on a call today. Every recommendation in this issue and in my previous comment was accepted, with one exception: C5 stays open. Recording the outcome here; anyone on the call should correct me if I have it wrong.

    Item Decision
    A1 A sync that cuts budget.total or a period amount below the committed amount is rejected with VALIDATION_ERROR and the previous plan stays in force. The sentence at specification.mdx:620 is replaced and the reference agent gains the missing sync-time check.
    A4 An authenticated caller that fails the approved_sellers evaluation receives verdict: "denied" with a seller_compliance finding and a check_id, so the attempt is audit-logged. A caller whose identity is missing or cannot be authenticated still receives PERMISSION_DENIED with no audit entry.
    A4, delegations Delegation failures move with it: an authenticated buyer-side caller outside delegations receives denied with a delegation_authority finding. The row at tasks/check_governance.mdx:744 narrows to missing or unauthenticated identity, and the audit-trail example becomes an execution check.
    B1 The human-review MUST applies in every governance mode.
    B2 Drop required from both then branches and keep const: true: omission is accepted and the agent sets the flag, an explicit false stays rejected. Remove "default": false at sync-plans-request.json:293, and state at specification.mdx:917 that schema default annotations are never applied to the hash preimage.
    C1 plan_id is unique per owner principal; reuse by another principal is PERMISSION_DENIED.
    C2 As proposed: an execute_only delegate acts only on bindings that already hold an approved intent check and may not open a new intent.
    C3 As proposed: a request with no geography, or country level only, is outside a regions-restricted plan. Intent checks return conditions, execution checks return denied.
    A2, A3, A5 to A9, B3, C4 Accepted as written.

    C5 remains open

    The question is the trailing-window aggregation key at specification.mdx:400, now that no governance schema carries account_id. One refinement since my previous comment, which supersedes its option 1.

    Keep a three-part tuple. Option 1 proposed the owner principal alone for buyer-side thresholds. That loses what account_id did, which was to keep one buyer's clients apart. A buyer principal that syncs plans for several advertisers would pool their spend, and one advertiser's buys could trip another's human-review threshold. That is the widening specification.mdx:421 names ("collapsing across account_id so two accounts share an aggregate"). Every plan already carries a required brand (sync-plans-request.json:33-36, required at :422), so the tuple can keep its shape with a field that exists:

    (owner principal, brand, seller agent)
    

    Each commit is recorded under the full tuple, and each threshold states which dimensions it sums over. The section's "correct tuple" and "wider key tuple" language keeps working, and an auditor can re-derive both the per-seller and the cross-seller figure from the same records.

    Two questions are left for the group:

    1. Is brand the right replacement for account_id? For portfolio plans the schema says brand "is the holding company or parent organization", so aggregation would happen at that level. That may be intended, and should be stated either way.
    2. Do the buyer-side thresholds sum across the seller dimension or within it? These are the three the section names: reallocation_threshold, human_review_required trigger points and registry-policy dollar floors. Summing within one seller leaves cross-seller fragmentation open, which would then need documenting as out of scope. Summing across sellers closes it, with limits defined per seller, such as budget.per_seller_max_pct (sync-plans-request.json:63-66), still summed within one seller.

    Either answer is a normative change, and :421 needs a new example. C5 does not need to block the accepted items; it can be split into its own issue if that is easier to track.

    Citations re-verified against 8114430 with Claude Code assistance; re-verify at implementation time.

  5. bokelley commented on Nov 11, 2026

    @bokelley
    Contributor

    Thanks — this is exactly the sweep the governance pages needed. Pinning the tree and listing what's already fixed saves a lot of triage. I spot-checked against main today; A1 through A8, B1, B2 and C5 are all still present as you describe.

    Proposed resolution, in three PRs so the uncontroversial part isn't held up by the decisions:

    PR 1: errata, doc-only (the losing page simply changes). A2, A3, A5, A6, A7, A8, A9, B3 (mark the legacy check_governance response branch as 3.0-compat in its description) and C5 (re-key the aggregation tuple on the owner principal, (owner_principal, seller_agent), since #6214 removed account_id). In each of these, the specification or the schema already wins, so this is a correction and patch-eligible, and we'd backport it to 3.2.x. It can go up now.

    PR 2: normative decisions (doc + enum descriptions). Where the spec contradicts itself, these are the picks, and they match your recommendations:

    • A1: a sync that reduces budget.total or a period amount below committed spend is rejected with VALIDATION_ERROR and leaves the plan unchanged. The reference agent gets the missing sync-time budget.total check.
    • A4: an unapproved seller gets PERMISSION_DENIED, evaluated against the target service that becomes the token aud (specification.mdx). The audit-trail example is rewritten to show the error.
    • B1: human_review_required is mode-independent. Audit mode "always returns approved" except for plans with human_review_required: true, which escalate in every mode.
    • C1–C3, C4.3, C4.4: your one-sentence answers as proposed.

    PR 3: schema. B2: drop required from both then branches in sync-plans-request.json and keep const: true. Explicit false is still rejected, an omitted flag is accepted, and the agent sets it. The prose changes from "overrides" to "rejects" a caller-supplied false, and known-limitations.mdx names the field the schema actually constrains. This widens what the schema accepts, so it goes to 3.3/main, not a 3.2.x patch. C4.1 and C4.2 ship as x-adcp-validation annotations now, and the schema tightening goes on the 4.0 list in #8756.

    B2 also settles part of adcp-client-python#1852 (whether an omitted flag is a valid request), so we'll link the two.

    If you'd like to take PR 1, go ahead. PRs 2 and 3 can follow once there's no objection here to the picks above.

  6. lukasz-pubx commented on Nov 11, 2026

    @lukasz-pubx
    ContributorAuthor

    Thanks @bokelley, the three-PR split works for me, and I'll take PR 1 with the scope you listed: A2, A3, A5, A6, A7, A8, A9, B3 (legacy branch marked 3.0-compat in its description) and C5.

    C5: accepting (owner_principal, seller_agent). I want to record this explicitly, because the working group left C5 open on the 2026-11-10 call and I had since suggested a three-part key with brand in the third slot. I'm withdrawing that suggestion. No governance schema carries account_id at main or at v3.2.8, so no agent can key on it today, and re-keying on the owner principal describes what a conformant agent can already do. That also means my earlier note calling the change normative overstated it; errata is a fair classification. In PR 1 the edit covers specification.mdx:400 and :429, and :421, which currently gives "collapsing across account_id" as its example of a widened key and needs a different example. Delegated sub-agents keep folding into the delegating principal as :400 already says. The question the group raised on the call, whether buyer-side thresholds should also aggregate across sellers, is separate from this correction and is not blocked by it. If anyone from the call sees C5 differently, this thread is the place to say so before PR 1 merges.

    One objection to the PR 2 picks: A4. The pick above is my original recommendation, but the working group decided the other way on the call, and the issue description was updated on 2026-11-10 to match:

    • An authenticated caller that fails the approved_sellers evaluation gets verdict: "denied" with a seller_compliance finding and a check_id, so the attempt is in the audit log. The group's reason was that a rejected attempt by an unapproved seller has to be visible to auditors.
    • Delegation failures get the same treatment, with a delegation_authority finding.
    • PERMISSION_DENIED stays for a caller that is unauthenticated or whose authenticated identity does not match the declared caller.

    The reference agent already returns the finding for an unapproved seller (server/src/training-agent/governance-handlers.ts:2072-2083), so the verdict shape is the smaller change there. The A4 section of the description lists the edits and the two gates in the reference agent that would change.

    One addition for PR 3: the default on human_review_required. The group also accepted removing "default": false at sync-plans-request.json:293 as part of B2. Once omission is valid, a consumer that applies the schema default turns a valid omitted field into an explicit false, which the then branches reject. That is the part of adcontextprotocol/adcp-client-python#1852 this issue settles. Details are in the B2 section of the description.

    The other picks match what the group agreed.

    Checked against ea017e1; the governance docs, schemas and reference-agent handlers are unchanged since the description was last verified.

  7. lukasz-pubx commented on Nov 11, 2026

    @lukasz-pubx
    ContributorAuthor

    A correction to my previous comment on C5, found while preparing PR 1.

    I wrote that no governance schema carries account_id at main or v3.2.8, "so no agent can key on it today", and that errata was therefore a fair classification. The first half is true but the inference is not. No governance schema has ever carried an account_id field, from 3.0.0 onward. The third element of the key was always derived: the 3.0 and 3.1 request schemas said "the governance agent resolves account from the plan", and get-plan-audit-logs-request.json:21 on main still says "Plans uniquely scope account and operator … the governance agent resolves account from each plan". What #6214 changed was that wording in check-governance-request.json and report-plan-outcome-request.json, which now describe the plan as owned by the authenticated buyer principal.

    So an agent can key on a derived account today, and one that does satisfies the conformance row at specification.mdx:429-436 now and would not after the re-key to (owner_principal, seller_agent). That makes C5 a behaviour change for such agents, not only a correction.

    I still think (owner_principal, seller_agent) is the right key under the owner-principal model. The open point is only whether it belongs in the patch-eligible PR 1 or in PR 2. PR 1 will carry it as scoped, with this spelled out in the description, so that it can be moved without affecting the rest.

  8. lukasz-pubx commented on Nov 12, 2026

    @lukasz-pubx
    ContributorAuthor

    PR 1 is up as #8931, with the scope from the split above: A2, A3, A5 to A9, B3 and C5. All checks pass and the IPR signature is recorded. The description of this issue is updated to match, including the corrected history for C5.

    @bokelley, three points from this thread are still open and need a decision:

    1. C5 placement. Whether the re-key to (owner_principal, seller_agent) belongs in the patch-eligible PR 1 or in PR 2, given that it changes behaviour for an agent that keys on an account derived from the plan. The PR is written so that C5 can move without affecting the rest.
    2. A4. The split lists PERMISSION_DENIED for an unapproved seller. The working group decided on a denied verdict with a seller_compliance finding, so that the attempt is in the audit log. PR 2 depends on which of the two stands.
    3. B2. Whether removing "default": false at sync-plans-request.json:293 goes into PR 3 with the rest of B2.
  9. bokelley commented on Nov 13, 2026

    @bokelley
    Contributor

    @lukasz-pubx thanks, and sorry for the lag. On your three points:

    1. C5: keep it in docs(governance): align campaign-governance pages with the specification and schemas #8931. It merges to main and ships in 3.3. You're right that it changes behaviour for an agent that keys on an account derived from the plan, so it doesn't belong in a patch. The 3.2.x backport of docs(governance): align campaign-governance pages with the specification and schemas #8931 will leave the C5 hunks out.
    2. A4: the working group's decision stands, and my split was out of date. An authenticated caller that fails approved_sellers gets verdict: "denied" with a seller_compliance finding and a check_id. Delegation failures get the same, with a delegation_authority finding. PERMISSION_DENIED stays for a caller that is unauthenticated or whose identity doesn't match caller. PR 2 should be written that way.
    3. B2: yes, removing "default": false at sync-plans-request.json:293 goes into PR 3.

    PRs 2 and 3 target 3.3. If they're up by Monday they can make rc.0; otherwise they go in as RC fixes. #8931 is approved and merging now.

  10. lukasz-pubx commented on Nov 14, 2026

    @lukasz-pubx
    ContributorAuthor

    @bokelley thanks, those three answers are applied. PRs 2 and 3 are up against main, ahead of the Monday cut for rc.0. They are independent of each other.

    PRs 2 and 3 touch two adjacent rows of the sync_plans error table, so whichever merges second needs a small rebase.

    PR 2 departs from the wording accepted on the 2026-11-10 call in three places. In each, the accepted wording conflicted with a rule that is already in the specification, and the PR follows the existing rule. These are the points to confirm or overrule; the PR description quotes the rule for each.

    1. C1 states a per-owner namespace for plan_id. Rejecting a second principal with PERMISSION_DENIED would reveal that a plan ID exists, which the PLAN_NOT_FOUND definition forbids, and the reference agent has namespaced plans per owner since feat(governance): define cross-role enforcement #6214. The issue did not mention either when it proposed C1.
    2. C2 does not let an execute_only delegate run execution checks, because only the seller that is the token audience can make that call. It keeps the definition of a pre-approved action and the prohibition.
    3. A4 follows your answer, and adds one sentence: governance mode does not relax who may call. A finding about the target seller still follows mode.

    Found while preparing these, and not fixed, because each needs a rule that does not exist yet. A recommendation is given where the existing text points one way.

    1. Multi-plan sync_plans. Nothing says whether one invalid plan rejects the whole request. The response schema allows a per-plan status: "error", and the reference agent rejects the whole request and never emits it. Recommend all-or-nothing, since the response has no per-plan error carrier.
    2. consultation_context across repeated conditions. Nothing says the handle stays the same. C4.4 now defines "the same action" by it, so an agent that mints a new handle each time never reaches the three re-call limit. Recommend that the agent returns the same handle for the whole negotiation, as the reference agent does.
    3. Re-sync below committed spend, beyond the total. A1 covers budget.total and period amounts. A re-sync can still cut budget.allocations.<type>.amount below what is committed to that type, or change budget.currency while spend is committed. Recommend the same VALIDATION_ERROR for both.
    4. Aggregation and governance mode. The trailing-window section says an agent that approves the second row of its example "is non-conformant", and the modes section says audit mode returns approved. The same section also speaks of a "human_review_required trigger at $10,000", though that field is a boolean and no plan field carries a dollar trigger for human review.
    5. Policy registry page. governance/policy-registry.mdx lists 14 policies that have no file under static/registry/policies, including us_coppa and alcohol_advertising, and does not list 33 that do. C4.3 makes an unresolvable ID an error, so it now matters which set is the registry.
    6. Reference agent behind the specification. It stores regions and delegations[].authority and reads neither, and it does not check flight order or policy ID uniqueness. These follow from existing text and from PRs 2 and 3, and are not in any of the three PRs.
    7. Overview diagram. images/concepts/budget-commitment-phases.png shows budget as "reserved" between check and outcome. PR 4 adds a sentence under it; the image needs redrawing.

    Checked against 01abd19.

  11. lukasz-pubx commented on Nov 14, 2026

    @lukasz-pubx
    ContributorAuthor

    @bokelley everything in this issue is now either merged or in an open pull request, and the description above is updated to match.

    What waits on a decision.

    1. The three places where PR 2 departs from the wording accepted on the 2026-11-10 call: C1, C2 and A4. They are set out in the comment above, and each now has a note under its item in the description.
    2. The seven items in that comment that need a new rule. None is in any of the pull requests.

    One point that affects merge order. PRs 3 and 4 each add a test file to the single-line test:schemas script in package.json. They conflict whenever another pull request that adds a schema test merges first, which has happened twice today. Each time the branch takes the list from main and re-adds its own tests, so the merge commits on those branches contain nothing else.

    Checked against bbf10ef.

  12. bokelley commented on Nov 16, 2026

    @bokelley
    Contributor

    Decision record update (2026-11-15): two of the picks are revised to match the uniform-response rule. The review on #9006 found that both conflicted with it.

    PLAN_NOT_FOUND must be returned uniformly for any plan_id the calling account can't access, never telling "exists but unauthorized" apart from "does not exist" (error-code.json). A resolve-then-deny path must not write tenant audit rows (error-handling.mdx, uniform-response rule). As recorded, both picks would have let a caller with no access learn that a plan exists.

    • A4, delegation failures (revised).
      • Was: every authenticated buyer-side agent outside delegations gets denied with a delegation_authority finding.
      • Now: a caller with no access to the plan gets PLAN_NOT_FOUND, the same response as for an unknown plan, with no audit row. A caller that can see the plan but falls outside delegations gets denied with a delegation_authority finding, audit-logged.
      • The attempts the working group wanted audited, by actors already tied to the plan, are still audited.
    • C1, plan_id uniqueness (revised).
      • Was: plan_id is unique per owner principal, and another principal reusing an id gets PERMISSION_DENIED.
      • Now: plan_id is scoped per owner principal. Another principal's sync_plans with the same id creates or updates that principal's own plan.
      • The PERMISSION_DENIED clause is dropped: answering "in use" for one id and success for another leaks existence.

    Unchanged:

    Credit to @KonstantinMirin for catching the conflict and @lukasz-pubx for the original reading. #9006 carries the alignment.

  13. lukasz-pubx commented on Nov 18, 2026

    @lukasz-pubx
    ContributorAuthor

    All four pull requests for this issue are merged, so I am closing it. The description above is updated to the final state, with a result under each acceptance criterion, checked at 61a1638.

    What merged

    What this issue hands on

    One gap that no issue covers yet

    No compliance storyboard grades the rules that #9006 settled for check_governance. At 61a1638, nothing under static/compliance/source mentions PLAN_NOT_FOUND, seller_compliance or delegation_authority, and approved_sellers and delegations appear only in a plan-hash vector. This issue said that a scenario for A4 was worth adding, and that still holds for the denied verdict in every mode and for the PLAN_NOT_FOUND rule.

    Thanks @bokelley and @KonstantinMirin for the reviews and the decisions.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.community-reporteddocumentationImprovements or additions to documentationgovernanceIssue concerns the governance protocol domain

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions