spec(specialisms): deprecate sales-proposal-mode → sales-guaranteed

.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.

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:

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

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",