Skip to content

docs(compliance): add capability-flag → scenario cross-reference index #4042

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
bokelley wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs(compliance): add capability-flag → scenario cross-reference index #4042

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .changeset/capability-flag-scenario-cross-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
---
---

docs: add capability-flag → scenario cross-reference section to compliance-catalog.mdx

Adds a "Capability-gated scenarios" section to the compliance catalog that maps each
`get_adcp_capabilities` flag to the scenarios it controls, so adopters can understand
how a flag toggle changes their grading surface without grepping scenario YAMLs.

Also updates `sales-proposal-mode` specialism status from `stable` to `deprecated` in
the catalog table and adds a migration note, matching the enum's `x-deprecated-enum-values`
declaration.

Closes #4039.
22 changes: 21 additions & 1 deletion docs/building/verification/compliance-catalog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ Specialisms are grouped below by parent protocol.
|-----------|--------|---------|
| `sales-guaranteed` | stable | Guaranteed media buys with human IO approval |
| `sales-non-guaranteed` | stable | Non-guaranteed auction-based media buys |
| `sales-proposal-mode` | stable | Media buys negotiated via proposal acceptance |
| `sales-proposal-mode` | deprecated | Proposal-mode selling — absorbed into `sales-guaranteed` + `media_buy.supports_proposals: true`. Do not claim for new agents. |
| `sales-catalog-driven` | stable | Catalog-driven commerce with conversion tracking |
| `sales-broadcast-tv` | stable | Broadcast linear TV with guaranteed inventory and FCC cancellation rules |
| `sales-social` | stable | Social media advertising platform with self-service flows |
Expand All @@ -102,6 +102,10 @@ Specialisms are grouped below by parent protocol.
**Coming in 3.1.** `sales-streaming-tv` (CTV / streaming), `sales-exchange` (programmatic SSP / exchange), and `sales-retail-media` (retail media network) are scheduled for 3.1. Sellers in those categories should claim `sales-guaranteed` or `sales-non-guaranteed` at 3.0 GA.
</Note>

<Note>
**`sales-proposal-mode` deprecated.** Proposal-driven selling is now handled by `sales-guaranteed` with `media_buy.supports_proposals: true`. New agents should claim `sales-guaranteed`; the runner grades the proposal lifecycle (`media_buy_seller/proposal_finalize`) when `supports_proposals: true` and skips it when `false`. The `sales-proposal-mode` ID remains valid for existing implementations and will be removed in a future major version.
</Note>

<Note>
`audience-sync` moved from the `governance` protocol to `media-buy` to match its tool family. If your agent claims `audience-sync` but only declares `governance` in `supported_protocols`, add `media_buy` to `supported_protocols` — the runner now expects the media-buy baseline to run alongside the audience-sync storyboard.
</Note>
Expand Down Expand Up @@ -165,6 +169,22 @@ The storyboard runner:

If any `stable` storyboard fails, your agent is not compliant for that claim. See [Validate Your Agent](/docs/building/verification/validate-your-agent) for how to run the suite locally.

## Capability-gated scenarios

Some compliance scenarios only execute when the seller explicitly declares a matching capability flag in `get_adcp_capabilities`. Setting a flag to `false` opts out of the scenario — the runner grades it `capability_unsupported` (a skip, not a fail) rather than executing the steps. This lets sellers scope their compliance surface to the features they actually support.

{/* Lint: NO automated enforcement — this table is maintained by hand against
requires_capability: blocks in static/compliance/source/protocols/**\/scenarios\/**\.yaml.
Verify this table when adding or removing a capability-gated scenario YAML. */}

| Capability flag | Default (when absent) | When `true` | When `false` |
|---|---|---|---|
| `media_buy.supports_proposals` | treated as `true` — runs (graded) | `media_buy_seller/proposal_finalize` runs — graded as part of the `sales-guaranteed` storyboard | `capability_unsupported` — scenario skips, not a compliance fail |

<Note>
When `media_buy.supports_proposals` is omitted, the compliance runner treats it the same as `true` — the `proposal_finalize` scenario runs and is graded. To opt out, declare `false` explicitly. Direct-buy guaranteed sellers (auction PG, retail SKU, quoted-rate) declare `false`; full-service guaranteed sellers that generate curated proposals declare `true`.
</Note>

## Naming conventions

Four casings coexist in the taxonomy. Which one applies depends on where the identifier is read:
Expand Down
2 changes: 1 addition & 1 deletion static/schemas/source/protocol/get-adcp-capabilities-response.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,7 @@
},
"supports_proposals": {
"type": "boolean",
"description": "Whether this seller commits to the proposal lifecycle on get_products: when called with buying_mode: 'brief' the seller will return at least one entry in proposals[]; when called with buying_mode: 'refine' + action: 'finalize' the seller will transition a proposal from draft to committed. A declaration of true is a commitment the seller will be graded against, not just a feature flag — sellers that decline a brief on policy grounds still owe a structured proposal-shaped rejection rather than an empty proposals[]. Most guaranteed-deal sellers (premium pubs, broadcast, CTV) declare true; auction-based PG, retail SKU, and quoted-rate direct-buy flows declare false. When false or absent, the seller serves products directly without proposal abstraction; conformance runners skip proposal-lifecycle storyboards.",
"description": "Whether this seller commits to the proposal lifecycle on get_products: when called with buying_mode: 'brief' the seller will return at least one entry in proposals[]; when called with buying_mode: 'refine' + action: 'finalize' the seller will transition a proposal from draft to committed. A declaration of true is a commitment the seller will be graded against, not just a feature flag — sellers that decline a brief on policy grounds still owe a structured proposal-shaped rejection rather than an empty proposals[]. Most guaranteed-deal sellers (premium pubs, broadcast, CTV) declare true; auction-based PG, retail SKU, and quoted-rate direct-buy flows declare false. When false, the seller serves products directly without proposal abstraction; conformance runners skip proposal-lifecycle storyboards. When absent, the compliance runner treats the flag as true — the proposal lifecycle runs and is graded; declare false explicitly to opt out.",
"default": false
},
"features": {
Expand Down
Loading