spec(storyboards): training-agent 5.7 audit fixes (#2627, #2628, #2629)

[bokelley]

Summary

Four issues filed from the training-agent 5.7 adoption storyboard audit. Three fix spec/storyboard content; one is upstream-only.

• Closes brand_rights storyboard conflates advertiser brand_id with talent brand_id #2627 — brand-rights/index.yaml > get_rights.sample_request was passing the advertiser brand_id (captured from get_brand_identity, e.g., acme_outdoor) into get_rights.brand_id, which per the request schema filters by rights-holder brand (e.g., talent like daan_janssen). Two fields, same name, different entities. Dropped the mis-assignment and added buyer_brand so compatibility filtering works as specified. Narrative now calls out the two brand_id semantics explicitly. Dead context_outputs capture removed after review.

• Closes Storyboard contradiction: double-cancel. state_machine permits idempotent-accept, invalid_transitions requires NOT_CANCELLABLE #2628 — state-machine.yaml > recancel_buy said "either return an error or accept idempotently" with no assertions, while invalid_transitions.yaml > second_cancel already required NOT_CANCELLABLE. No single implementation could pass both. Aligned recancel_buy with the NOT_CANCELLABLE vector — matches the §128/§129 resolution being finalized in spec: pre-GA tightening — re-cancel error code (#2617) + request body well-formedness (#2523) #2619 (cancellation-specific code takes precedence over generic terminal-state INVALID_STATE). Narrative for the terminal_enforcement phase now clarifies that pause/resume on canceled buys still return INVALID_STATE so implementers don't over-generalize.

• Closes schema_validation storyboard: past-start any_of branches reported as step failures #2629 — schema-validation.yaml past-start handling has two optional: true branches (past_start_reject_path, past_start_adjust_path) both contributing to past_start_handled. A conformant agent picks one path; the other's expect_error/field_present assertion fails because the agent took the opposite behavior, and the runner surfaces the non-taken branch's failure in the summary. Added a new canonical skip reason peer_branch_taken in runner-output-contract.yaml (distinct from not_applicable — keeps coverage gaps separable from runtime branch routing in dashboards). Added the per-step grading rule in storyboard-schema.yaml with authoring constraint (branch-set peers MUST be optional: true) and runner detection rule. Cross-referenced from docs/contributing/storyboard-authoring.md.

#2626 — filed upstream, no spec change required

The sales_catalog_driven storyboard's sample_request already sends the spec-conformant fields (performance_index, metric_type, feedback_source). The bogus feedback.satisfaction payload comes from a hardcoded provide_performance_feedback override in @adcp/client's src/lib/testing/storyboard/request-builder.js that bypasses the storyboard. Filed at adcontextprotocol/adcp-client#689; commented on #2626 to track.

Expert review applied

Second commit (d98f21b) addresses feedback from protocol / product / docs / code reviews:

• Restored idempotency_key on recancel_buy — without it, a conformant agent could reject for missing-key rather than NOT_CANCELLABLE, failing the step for the wrong reason. Matches the pattern used by schema-validation.create_buy_past_start_reject.
• Distinct peer_branch_taken skip reason (not overloading not_applicable) — separates coverage gaps from runtime branch routing for downstream tooling.
• Removed dead brand_id context_outputs capture in brand-rights (no consumer after the buyer_brand fix).
• Defined "aggregation flag" on first use, split authoring vs. runner guidance in the schema comment, canonicalized the peer_branch_taken detail shape for downstream parsing.
• Authoring constraint added: every phase in a branch set MUST be optional: true.

Follow-ups filed (out of scope for this PR)

• Promote branch_set to first-class storyboard schema construct #2633 — Promote branch_set: to first-class storyboard schema construct
• Storyboard contradiction lint — catch peer-storyboard contradictions pre-merge #2634 — Storyboard contradiction lint (pre-merge CI)
• Known-ambiguities entries for PR #2631 storyboard audit findings #2635 — Known-ambiguities entries for the four PR findings
• brand_rights get_rights — assert compatibility filtering was actually exercised #2636 — brand_rights compatibility-filtering assertion (prove filtering actually ran, not just accepted)
• invalid_transitions.second_cancel missing idempotency_key on expect_error step #2637 — invalid_transitions.second_cancel missing idempotency_key (same pattern as the recancel_buy fix)

Test plan

• npm run build:compliance succeeds — compiled storyboards emit to dist/compliance/latest/
• npm run test:unit (precommit) — 631 tests pass (both commits)
• npm run typecheck — clean
• npm run test:error-codes — no new warnings (existing duplicate-key warning on runner-output-contract.yaml > summary is pre-existing)
• npm run test:storyboard-scoping — passes
• Spec review: confirm the NOT_CANCELLABLE alignment is consistent with spec: pre-GA tightening — re-cancel error code (#2617) + request body well-formedness (#2523) #2619's §128/§129 resolution
• Spec review: confirm peer_branch_taken as a distinct skip reason is the right direction vs. overloading not_applicable

🤖 Generated with Claude Code

[github-actions]

Schema Link Check Results

Commit: 38a5407 - Merge remote-tracking branch 'origin/main' into bokelley/fix-storyboard-issues

⚠️ Warnings (schema not yet released)

These schemas exist in source but haven't been released yet. The links will be broken until the next version is published:

• https://adcontextprotocol.org/schemas/v3/enums/specialism.json
  • Schema exists in latest (source) but not yet released in v3
  • Action: This link will work after next 3.x release is published

---

To fix: Either:

1. Wait for the next release and merge this PR after the release is published
2. Use latest instead of a version alias if you need the link to work immediately (note: latest is the development version and may change)
3. Coordinate with maintainers to cut a new release before merging