Phase 3: move storyboard scenarios into spec repo as canonical contract

[bokelley]

Background

adcp#4907 Phase 1 added bidirectional release gating: @adcp/sdk releases now validate a candidate runner against a tagged Python reference seller. Phase 2 will expand that to a reference-seller matrix.

Phase 3 should address the remaining ownership problem: storyboard scenarios currently live with @adcp/sdk, so the SDK is both the runner and the scenario source of truth. The spec repo should own the canonical storyboard scenario bundle, and SDKs should consume it.

Goal

Split responsibilities:

adcontextprotocol/adcp = canonical storyboard scenarios and scenario schema
adcontextprotocol/adcp-client / @adcp/sdk = runner that executes canonical scenarios
reference SDKs = implementations tested against canonical scenarios

Proposed rollout

1. Add a canonical scenario location in this repo, for example static/conformance/storyboards/ or static/storyboards/.
2. Add CI validation for scenario files and runner output contracts.
3. Copy the current @adcp/sdk storyboard scenarios into this repo without semantic changes.
4. Add an @adcp/sdk check proving its bundled/default scenarios match the canonical spec copy.
5. Teach the runner to load scenarios from an explicit path, package, or spec ref.
6. Switch reference SDK CI and cross-repo interop CI to use the spec-owned bundle.
7. Remove @adcp/sdk as the scenario authority after a compatibility window.

Sequencing policy to document

Breaking or materially stricter scenario changes should follow an explicit order:

spec scenario change -> reference sellers update -> @adcp/sdk runner release -> downstream consumers update

This avoids the release-order deadlock that motivated adcp#4907.

Acceptance

• Canonical storyboard scenarios live in this spec repo.
• Scenario schema/contract validation runs in spec CI.
• @adcp/sdk can run against the spec-owned scenario bundle.
• Existing scenario semantics are preserved during the initial migration.
• The versioning and rollout policy for scenario changes is documented.
• Phase 2 reference-seller matrix can point at one canonical scenario source.

References

• Parent RFC: RFC: bidirectional storyboard interop CI — @adcp/sdk releases gated on reference-impl conformance #4907
• Phase 1 SDK gate: ci: add Python reference seller interop gate adcp-client#1986
• Python harness precedent: ci: extract reference seller storyboard harness adcp-client-python#818

[bokelley]

Triage

Classification: Feature request (Phase 3 tracking issue)
Bucket(s): compliance-suite
Status: deferred

Blocked-on: #4907 — resurfaces on merge

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01LMayVjtKvQe12Jy8qvxsEU

---

Generated by Claude Code

[bokelley]

Unblocked: #4907 Phase 1 and Phase 2 are complete.

Next implementation should be the additive first slice:

• mirror current @adcp/sdk storyboard scenarios into this spec repo
• add validation/drift checks
• document the scenario rollout policy
• do not switch runtime authority yet

The goal is to establish spec-owned scenario artifacts without changing runner behavior in the same PR.