feat(media-buy): refine[] prefixed ids + optional action (adcp#2775)

[bokelley]

Summary

Closes #2775. Rearchitects the refine[] array on get_products to align with AdCP's existing naming conventions and match the shape that storyboard authors were already writing.

• Prefixed ids: id → product_id inside scope: "product", id → proposal_id inside scope: "proposal". Every other entity id in AdCP is prefixed (media_buy_id, plan_id, creative_id, account_id…) — this was the only island.
• Optional action with default: "include" on product and proposal scopes. Authors writing { scope: "product", product_id: "x", ask: "…" } no longer need the "action": "include" ceremony; the verb appears only when the behavior is non-default (omit / more_like_this / finalize).
• Symmetric response: refinement_applied[] is now a discriminated oneOf echoing the same prefixed ids, with scope + the matching id field required per branch so cross-validation is a contract, not a convention.
• Codegen friendliness: added an OpenAPI-style discriminator: { propertyName: "scope" } annotation on both request refine[] and response refinement_applied[] for clean TypeScript / Python / Pydantic narrowed unions.

Pre-GA (current version 3.0.0-rc.3), so breaking shape changes are cheap. Documented in the 3.0 release notes with a before/after migration table.

Before / after

// before
{ "scope": "product",  "id": "p1",  "action": "include", "ask": "add 16:9" }
{ "scope": "proposal", "id": "pr1", "action": "finalize" }

// after
{ "scope": "product",  "product_id":  "p1",  "ask": "add 16:9" }
{ "scope": "proposal", "proposal_id": "pr1", "action": "finalize" }

Touched

• Schemas: get-products-request.json, get-products-response.json
• Docs: refinement.mdx, get_products.mdx, specification.mdx, intro.mdx, media-products.mdx, whats-new-in-v3.mdx
• Server: training-agent/task-handlers.ts + unit test for the action-default behavior
• Allowlist: dropped 4 stale storyboard-drift entries now that storyboards match the canonical shape
• Changeset: refine-prefixed-ids-optional-action.md (major bump, with migration table)

Test plan

• npm run build:schemas clean
• npm run test:schemas ✓
• npm run test:examples ✓
• npm run test:composed ✓
• npm run test:json-schema ✓
• npm run typecheck ✓
• Storyboard schema-ref lint ✓ (37 grandfathered, 0 new drift)
• build:compliance ✓ (all 7 storyboard lints pass)
• Refine-mode unit tests ✓ (3/3, including new default-action test)
• Reviewed by ad-tech-protocol-expert, adtech-product-expert, code-reviewer subagents — all must-fix items addressed

Related but out of scope

• Schema: context field collision — SI schemas redefine core context as string with semantic meaning #2774 (SI context field collision) — separate PR
• Schema docs: governance report/audit schemas reject account — author intuition collides with plan_id scoping #2776 (governance account field) — separate PR
• Schema: creative-manifest.assets uses 14-branch anyOf without discriminator — ecosystem-wide validator noise #2777 (creative-manifest anyOf → oneOf discriminator) — separate PR

🤖 Generated with Claude Code