diff --git a/.changeset/deprecate-sales-proposal-mode.md b/.changeset/deprecate-sales-proposal-mode.md new file mode 100644 index 0000000000..a2dc9e81e5 --- /dev/null +++ b/.changeset/deprecate-sales-proposal-mode.md @@ -0,0 +1,20 @@ +--- +"adcontextprotocol": minor +--- + +spec(specialisms): deprecate sales-proposal-mode (refs #3823 item 4, #3844) + +Proposal mode is how guaranteed deals get sold in practice — RFP → proposal → review → finalize → IO signing → live. Auction-based sales don't have proposals; they're bid-by-bid. Today `sales-proposal-mode` (proposals + briefs) and `sales-guaranteed` (IO + guaranteed) are halves of the same flow that force sellers to declare both or pick the wrong one. + +Following the established `signed-requests` precedent (deprecated in 3.1, retained until 4.0): + +- Adds `sales-proposal-mode` to `x-deprecated-enum-values` in `static/schemas/source/enums/specialism.json` +- Updates `enumDescriptions[sales-proposal-mode]` with the deprecation note + migration path +- Adds a deprecation banner to the storyboard at `static/compliance/source/specialisms/sales-proposal-mode/index.yaml` +- Updates `sales-guaranteed`'s narrative to explain how proposal flows relate to guaranteed selling and why proposal_finalize is not yet folded into its `requires_scenarios` + +The clean folding of `proposal_finalize` into `sales-guaranteed.requires_scenarios` (so both flavors of guaranteed selling grade against the proposal lifecycle) needs a wire-level capability flag the storyboard runner can use to skip the scenario as `not_applicable` for direct-buy guaranteed sellers (auction PG, retail SKU; no RFP). The runner gates only on `requires_capability` predicates against `get_adcp_capabilities`, not on scenario-level metadata. Tracked as a follow-up in #3844 (`add supports_proposals capability flag`). + +**Migration through 3.x**: sellers that do proposals continue to declare BOTH `sales-guaranteed` AND `sales-proposal-mode` so the proposal flow grades under the proposal-mode specialism's existing storyboard bundle. Pure-direct-buy guaranteed sellers (auction PG, retail SKU) declare only `sales-guaranteed`. The wire shape is unchanged — both enum values remain valid through 3.x. + +**At 4.0**: with the `supports_proposals` capability flag in place (#3844), `proposal_finalize` joins `sales-guaranteed.requires_scenarios` with capability-gated skip semantics, the `sales-proposal-mode` enum value is removed, and the storyboard bundle is retired. diff --git a/static/compliance/source/specialisms/sales-guaranteed/index.yaml b/static/compliance/source/specialisms/sales-guaranteed/index.yaml index 81bad5d0ed..d15558b6f9 100644 --- a/static/compliance/source/specialisms/sales-guaranteed/index.yaml +++ b/static/compliance/source/specialisms/sales-guaranteed/index.yaml @@ -40,6 +40,19 @@ narrative: | is modelled entirely at the A2A task layer; there is no interim "pending_approval" media buy status (that value only exists on Account.status, not MediaBuy.status). + Proposal-driven workflows are part of guaranteed selling: most guaranteed deals start with + an RFP/brief, generate a proposal with curated bundles and rationale, refine, finalize to + committed status with firm pricing and an inventory hold, and then the buyer accepts via + create_media_buy. The `media_buy_seller/proposal_finalize` scenario covers that flow but + is NOT (yet) in this specialism's `requires_scenarios` because the storyboard runner + cannot currently grade it as `not_applicable` for sellers without proposal support — there + is no `requires_capability` path in `get_adcp_capabilities` for "this seller supports + proposals" (tracked at #3844). Until that capability flag exists, sellers that do + proposals should declare BOTH `sales-guaranteed` AND `sales-proposal-mode` through 3.x; + pure-direct-buy guaranteed sellers (auction PG, retail SKU) declare only `sales-guaranteed`. + At 4.0, with the capability flag in place, `proposal_finalize` joins `sales-guaranteed`'s + `requires_scenarios` and the `sales-proposal-mode` enum value is removed. + agent: interaction_model: media_buy_seller capabilities: diff --git a/static/compliance/source/specialisms/sales-proposal-mode/index.yaml b/static/compliance/source/specialisms/sales-proposal-mode/index.yaml index 5b26504dcc..a18dd713b0 100644 --- a/static/compliance/source/specialisms/sales-proposal-mode/index.yaml +++ b/static/compliance/source/specialisms/sales-proposal-mode/index.yaml @@ -25,6 +25,13 @@ invariants: - status.monotonic narrative: | + **DEPRECATED in 3.1 — see https://github.com/adcontextprotocol/adcp/issues/3823** + Proposal-driven flows now grade under `sales-guaranteed`. Sellers that currently declare + `sales-proposal-mode` should additionally declare `sales-guaranteed` for the duration of + 3.x; this storyboard is retained for backward compat and removed at 4.0. The + `media_buy_seller/proposal_finalize` scenario remains accessible to agents that support + `buying_mode: 'refine'` regardless of which specialism declaration is used. + Your seller generates curated media plan proposals. The buyer sends a brief, your platform returns products alongside proposals — curated bundles with budget allocations and rationale for each recommendation. The buyer reviews, optionally refines, and then accepts a proposal diff --git a/static/schemas/source/enums/specialism.json b/static/schemas/source/enums/specialism.json index d728bef769..2108c15c9f 100644 --- a/static/schemas/source/enums/specialism.json +++ b/static/schemas/source/enums/specialism.json @@ -5,7 +5,8 @@ "description": "Specialized capability claims an agent can make. Each specialism maps to a compliance storyboard bundle published at /compliance/{version}/specialisms/{id}/. An agent asserts specialisms it supports in get_adcp_capabilities; the AAO compliance runner executes the matching storyboards to verify the claim.", "type": "string", "x-deprecated-enum-values": [ - "signed-requests" + "signed-requests", + "sales-proposal-mode" ], "x-deprecated-enum-values-doc": "Enum values listed here are retained for backward compatibility but their corresponding storyboard has been relocated or removed. Build-time parity checks (scripts/build-compliance.cjs verifyEnumParity) skip filesystem-backing enforcement for these values. Targeted for removal in a future major version.", "enum": [ @@ -46,7 +47,7 @@ "sales-catalog-driven": "Catalog-driven commerce with conversion tracking", "sales-guaranteed": "Guaranteed media buys with human IO approval", "sales-non-guaranteed": "Non-guaranteed auction-based media buys", - "sales-proposal-mode": "Media buys negotiated via proposal acceptance", + "sales-proposal-mode": "DEPRECATED in 3.1 — proposal-driven flows are conceptually part of `sales-guaranteed` (RFP → proposal → finalize → IO → live is one lifecycle). For 3.x, sellers that do proposals continue to declare BOTH `sales-guaranteed` AND `sales-proposal-mode` so the proposal flow grades under the proposal-mode specialism's existing `requires_scenarios`. Pure-direct-buy guaranteed sellers (auction PG, retail SKU; no RFP) declare only `sales-guaranteed`. This enum value is retained until 4.0 for backward compat. The clean merge — folding `proposal_finalize` into `sales-guaranteed.requires_scenarios` with capability-gated skip — needs a `supports_proposals` capability flag in `get_adcp_capabilities` so the runner can grade it as `not_applicable` for direct-buy sellers; tracked at #3844. At 4.0, with that flag in place, `sales-proposal-mode` is removed and proposal grading lives entirely under `sales-guaranteed`. See https://github.com/adcontextprotocol/adcp/issues/3823 (taxonomy consolidation).", "sales-social": "Social media advertising platform with self-service flows", "signal-marketplace": "Marketplace signal agent reselling third-party data", "signal-owned": "Owned signal agent exposing first-party segments",