docs(aao-verified): make Live independent of Spec#3536
Merged
Conversation
The prerequisite framing was wrong. A seller using @adcp/sdk who flows real production traffic but never bothered building a sandbox shouldn't have to stand up a mock endpoint just to earn (Spec) before (Live) can issue. The eight observability checks already exercise wire format, filters, lifecycle, and scope through real traffic — the simulation pass would be redundant for that seller. The two axes are now stated as orthogonal: each independently demonstrates conformance through different evidence (Spec via simulation, Live via real-traffic observation). Either is sufficient for the claims it covers. Updated: - aao-verified.mdx — top-level framing, (Live) eligibility table, badge-reading table, mark semantics list, lifecycle (revocations no longer cascade between axes). - conformance.mdx — containment paragraph rewritten as "both marks attest conformance via different evidence." No code changes — verification_modes already supported ['live'] standalone; the badge issuance logic never enforced a prerequisite. This was a docs-only correctness fix. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EmmaLouise2018
approved these changes
Apr 29, 2026
bokelley
added a commit
that referenced
this pull request
Apr 29, 2026
…spec docs (#3537) Cleans up the doc drift after PR #2153 (badge implementation + (Spec)/(Live) reframing) and PR #3536 (independence clarification). Internal contradiction in `conformance.mdx` resolved; six call-sites in `accounts/overview.mdx` qualified to (Live) where they pivot on `attestation_verifier`; three new sections in `aao-verified.mdx` (How to claim each qualifier, What AAO Verified is not, Relationship to supporting specs); changeset updated to reflect the orthogonal-axes framing. Reporting/runner-scope split surfaced via doc Note pointing at #3561. Pre-3.1 GA full sweep tracked in #3564. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced Apr 30, 2026
bokelley
added a commit
that referenced
this pull request
Apr 30, 2026
Three follow-ups to #3524: 1. Docs (docs/building/aao-verified.mdx). Last updated for the orthogonal-axes framing in #3536; didn't mention the per-version model that just shipped. Added a "Per-version badges" section, updated the SVG/embed sections with both URL shapes (legacy auto-upgrade and version-pinned), added adcp_version to the JWT claim block with explicit verifier guidance ("verifiers MUST check adcp_version against the AdCP version they care about" — closes the cross-version replay concern from Stage 2's security review), and added a brand.json enrichment subsection documenting the badges[] array and the deprecation policy. 2. Refactor for testability. The shaping logic that builds the aao_verification block was a closure inside the brand.json route handler — unreachable from unit tests. Extracted to services/aao-verification-enrichment.ts as buildAaoVerificationBlock(badges). The route handler keeps the JSON traversal and assignment; the builder is pure with 14 new unit tests covering empty input, single-badge, multi-version dedupe with caller-ordering preserved, modes_by_role flattening (the "buyer pinned to 3.0 sees the wrong contract" footgun), adcp_version shape filtering (defense in depth), and the deprecation notice content. Code-review nit on PR #3604. 3. PROTOCOL_LABELS audit comment in dashboard-agents.html. The `${protocol} Agent${versionSegment}` label construction relies on PROTOCOL_LABELS values not ending in "Agent" — added a comment pinning the invariant so a future contributor adding a new protocol doesn't accidentally produce "Foo Agent Agent 3.1". DX expert nit from #3603. No wire-format changes — brand.json output is byte-for-byte identical to what shipped in #3604. Panel UX changes (role grouping, "show all versions" disclosure) explicitly defer until parallel-version badges land in production with real buyer feedback to design against. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
bokelley
added a commit
that referenced
this pull request
Apr 30, 2026
…3654) Three follow-ups to #3524: 1. Docs (docs/building/aao-verified.mdx). Last updated for the orthogonal-axes framing in #3536; didn't mention the per-version model that just shipped. Added a "Per-version badges" section, updated the SVG/embed sections with both URL shapes (legacy auto-upgrade and version-pinned), added adcp_version to the JWT claim block with explicit verifier guidance ("verifiers MUST check adcp_version against the AdCP version they care about" — closes the cross-version replay concern from Stage 2's security review), and added a brand.json enrichment subsection documenting the badges[] array and the deprecation policy. 2. Refactor for testability. The shaping logic that builds the aao_verification block was a closure inside the brand.json route handler — unreachable from unit tests. Extracted to services/aao-verification-enrichment.ts as buildAaoVerificationBlock(badges). The route handler keeps the JSON traversal and assignment; the builder is pure with 14 new unit tests covering empty input, single-badge, multi-version dedupe with caller-ordering preserved, modes_by_role flattening (the "buyer pinned to 3.0 sees the wrong contract" footgun), adcp_version shape filtering (defense in depth), and the deprecation notice content. Code-review nit on PR #3604. 3. PROTOCOL_LABELS audit comment in dashboard-agents.html. The `${protocol} Agent${versionSegment}` label construction relies on PROTOCOL_LABELS values not ending in "Agent" — added a comment pinning the invariant so a future contributor adding a new protocol doesn't accidentally produce "Foo Agent Agent 3.1". DX expert nit from #3603. No wire-format changes — brand.json output is byte-for-byte identical to what shipped in #3604. Panel UX changes (role grouping, "show all versions" disclosure) explicitly defer until parallel-version badges land in production with real buyer feedback to design against. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
bokelley
added a commit
that referenced
this pull request
May 1, 2026
- Rename "Two marks: AdCP Conformant vs AAO Verified" section in aao-verified.mdx to "Naming history" — cold readers see the current single-mark framing, not a confusing two-marks heading - Fix malformed 3-column table row in the same section - Replace ⊆ containment notation in conformance.mdx with the independence-first phrasing established in #3536 - Update salty-wasps-cheat.md: remove "Spec is a prerequisite for measuring Live" (directly contradicts #3536 orthogonal-axes fix) - Update account-authorization-and-rbac-errors.md: qualify attestation_verifier as binding to the AAO Verified (Live) qualifier Item 4 of the sweep (attestation_verifier doc check conditional on #3561) remains open on the parent issue. Refs #3564 https://claude.ai/code/session_013WywfzRTvdv2kWUZdp7aBz Co-authored-by: Claude <noreply@anthropic.com>
6 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The merged AAO Verified docs framed (Spec) as a prerequisite for (Live). That's wrong. A seller using `@adcp/sdk` who flows real production traffic shouldn't have to stand up a sandbox/test endpoint just to earn (Spec) before (Live) can issue.
The two axes demonstrate conformance through different evidence:
Either is sufficient for the claims it covers. Some sellers can only earn one or the other:
Why this matters now
Before any seller in the ecosystem builds toward "I need (Spec) before I can earn (Live)" — which a couple of partner conversations were already heading. Forcing SDK-built agents to stand up a separate mock endpoint is busywork that proves nothing the SDK didn't already guarantee.
Files changed
What did not change
The badge code already supports `verification_modes: ['live']` standalone — the prerequisite was a stated convention, never enforced. So this is a docs-only correctness fix.
`verification_modes: ['live']` (without 'spec') is already a valid wire-format value:
Test plan
🤖 Generated with Claude Code