docs(compliance): storyboard troubleshooting + known-ambiguities guides (#2605, #2607, #2608)

[bokelley]

Summary

Two new implementer-facing docs that close the DX gap #2608 identified and document the current state of the open conformance ambiguities (#2605, #2607) so new implementers aren't paying 1:1 detective-work cost per unresolved issue.

docs/building/implementation/storyboard-troubleshooting.mdx

Failure-mode lookup keyed on the raw error messages new implementers see. Each section: what the runner is telling you → what it means → how to fix. Patterns covered:

• PRODUCT_NOT_FOUND → fixture seeding (comply_test_controller / static seed / alias)
• Missing WWW-Authenticate: Signature challenge on 401 → RFC 9421 challenge emission + signatureErrorCodeFromCause mapping
• errors[] vs adcp_error envelope drift → Spec: response envelope unification — errors[] vs adcp_error on failure responses #2587 tracking + interim guidance (return errors[])
• Context echo failures → echo every request context key back; Spec: context-echo semantics tightening (.* resolution and MUST-echo rules) #2589
• Capability-vector mismatches → declare + runner auto-skip + skipVectors escape hatch
• INVALID_STATE / INVALID_TRANSITION / INVALID_STATE_TRANSITION → canonical + lint location; Spec: error-code taxonomy lint + generated enum (INVALID_STATE_TRANSITION vs INVALID_TRANSITION etc.) #2588
• Idempotency missing_key SDK inversion → Testing infrastructure: idempotency 'missing key' vector can't probe through reference SDK client #2607
• account / brand stripping → declare required in schema

Plus operator escape hatches, a "before filing a bug" checklist, and cross-links to the canonical source docs.

docs/building/implementation/known-ambiguities.mdx

Running inventory of open spec ambiguities with interim guidance. Tagged Tracked / Under review / Resolved; each links to its upstream issue. Entries are deleted as issues close. Current set:

Ambiguity	Status	Issue
Envelope shape (errors[] vs adcp_error)	Under review	#2587
past_start_handled reject-or-adjust	Resolved (forwarding pointer)	#2389
Other any_of single-branch assertions	Tracked	#2605
Idempotency missing_key SDK inversion	Tracked	#2607
Vectors asserting schema-optional fields	Tracked	#2604
check_governance conditional-approval shape	Tracked	#2603
$context.* resolution rules	Under review	#2589
INVALID_STATE_TRANSITION canonicalization	Under review	#2588
Fixture-id hardcoding	Tracked	#2585

static/compliance/source/universal/idempotency.yaml

The missing_key phase gains an SDK-injection caveat note in its narrative, pointing at #2607. Implementers reading the YAML now see the caveat in-line without having to hunt down the troubleshooting doc.

Closes

• Implementer DX: troubleshooting guide + known-ambiguities doc #2608 — troubleshooting + known-ambiguities docs wired into Implementation Patterns nav.

Progresses

• Spec ambiguity: conformance vectors test single branch of spec any_of (past_start_handled et al.) #2605 — past_start is already resolved by spec(compliance): #2373 review follow-ups — schema-mutating lint + past_start_date split (#2376, #2377) #2389; other any_of candidates documented as Tracked in known-ambiguities with skipVectors workaround. Vector-level audit remains open as a follow-up.
• Testing infrastructure: idempotency 'missing key' vector can't probe through reference SDK client #2607 — idempotency SDK inversion documented in both new docs AND in-line in the storyboard narrative. Storyboard-runner raw-HTTP probe (the actual fix) remains open in the adcp-client repo; this PR doesn't touch that.

Test plan

• npm run test:docs-nav — passes (nav entries wired)
• npm run build:compliance — passes (YAML note doesn't break compilation)
• Full npm test via pre-commit — 631 tests pass, typecheck clean
• Changeset included
• Broken-links CI check validates cross-references

🤖 Generated with Claude Code

[github-actions]

Schema Link Check Results

Commit: a26c82a - docs(compliance): storyboard troubleshooting + known-ambiguities guides (#2608, #2605, #2607)

⚠️ 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

[bokelley]

Closing as obsolete — superseded by parallel-merged PRs.

What landed while this PR was open

• feat(docs+compliance): implementer DX — troubleshooting, known-ambiguities, idempotency opt-out (#2607, #2608) #2613 (merged ~4h before this close) created storyboard-troubleshooting.mdx and known-ambiguities.mdx with better content than this PR's duplicates, and set `omit_idempotency_key: true` on the missing-key step (the actual fix for Testing infrastructure: idempotency 'missing key' vector can't probe through reference SDK client #2607).
• spec(compliance): non-OAuth auth path + branchable-behavior pattern (#2605, #2606) #2611 (merged ~same window) added a "branchable behaviors" authoring pattern to `storyboard-authoring.md` and explicitly completed the Spec ambiguity: conformance vectors test single branch of spec any_of (past_start_handled et al.) #2605 audit with the conclusion: "no additional single-branch error_code asserts masking spec any_of behaviors."

What this PR's docs got wrong anyway

Code review caught several folklore defects that would have shipped stale even without the duplication:

• `comply_test_controller.seed_scenario` doesn't exist (real primitives: seed_product / seed_pricing_option / seed_creative / seed_plan / seed_media_buy)
• `signatureErrorCodeFromCause()` helper doesn't exist
• Challenge-header example included `realm="adcp"`, which `security.mdx §1103` explicitly forbids
• Context-echo guidance contradicted `context-sessions.mdx` rule 4 ("when caller provides no context, response MUST NOT fabricate one")
• All 8 referenced issues (Spec: response envelope unification — errors[] vs adcp_error on failure responses #2587, Spec: storyboards assert fields not required by response schemas (list_id echo, catalog counts, pricing_options, vendor_cost) #2604, Spec: conditional-approval response schema for check_governance — 'conditions' field shape undefined #2603, Spec: context-echo semantics tightening (.* resolution and MUST-echo rules) #2589, Spec: error-code taxonomy lint + generated enum (INVALID_STATE_TRANSITION vs INVALID_TRANSITION etc.) #2588, Spec: storyboard fixtures block / pattern — replace hardcoded fixture IDs #2585, Spec ambiguity: conformance vectors test single branch of spec any_of (past_start_handled et al.) #2605, Testing infrastructure: idempotency 'missing key' vector can't probe through reference SDK client #2607) closed within hours of this PR being drafted — entries labeled "Tracked" / "Under review" would have shipped describing resolved state

Open question that survived

The re-cancel vector's error-code assertion is a real spec ambiguity — `specification.mdx §129,254` says "Sales agents MUST reject updates to media buys in terminal states (`completed`, `rejected`, `canceled`) with error code `INVALID_STATE`." That MUST applies to re-cancel (a terminal-state update). `NOT_CANCELLABLE` is a MAY per §128. An agent returning `INVALID_STATE` on re-cancel is conformant with the MUST and currently fails the vector.

The #2611 audit called `NOT_CANCELLABLE` "scenario-canonical" but didn't resolve the conflict with the MUST. I'm filing a follow-up issue to surface that for a spec-owner decision rather than pushing a unilateral vector change here.