Pre-3.1 doc sweep: AAO Verified (Spec)/(Live) framing consistency

[bokelley]

Problem

The (Spec)/(Live) qualifier model for AAO Verified landed across several PRs in quick succession:

• feat: AAO Verified agent badge system #2153 — shipped the badge implementation + reframed aao-verified.mdx to (Spec)/(Live)
• docs(aao-verified): make Live independent of Spec #3536 — clarified that (Spec) and (Live) are independent axes, not hierarchical (corrected an earlier "(Spec) is a prerequisite for (Live)" statement)
• docs(aao-verified): reconcile (Spec)/(Live) qualifier framing across spec docs + add 3 sections #3537 — reconciled conformance.mdx's contradictory "Two marks" section, qualified six call-sites in accounts/overview.mdx, plus three new sections in aao-verified.mdx

This addresses the highest-friction cases. Before 3.1 GA we should do a full sweep so the doc set tells one coherent story.

What still needs auditing

1. Stale "AdCP Conformant" / "Tier 1" / "Tier 2" / "AAO Verified mark" residue

A grep across all docs and changesets for:

• AdCP Conformant — should generally become AAO Verified (Spec) or just stay neutral ("conformant" lowercase is fine when not naming the mark)
• Tier 1 / Tier 2 — fully retired language; flag any remaining occurrences
• AAO Verified mark (without qualifier) — distinguish: is this referring to the umbrella mark (fine) or specifically (Live) (needs qualification)?
• Verified ⊆ Conformant containment language — replace with the independent-axes framing

2. Pages likely to mention the badge that may not have been touched

• docs/building/compliance-catalog.mdx
• docs/building/validate-your-agent.mdx
• docs/building/get-test-ready.mdx
• docs/learning/overview.mdx and learning track pages (tracks/*.mdx)
• docs/community/working-group.mdx
• docs/reference/versioning.mdx
• docs/reference/known-limitations.mdx
• The skills (skills/*/SKILL.md)
• docs/intro.mdx and docs/quickstart.mdx

3. Independence framing — check for surviving prerequisite language

Per #3536, (Spec) and (Live) are independent. Audit for surviving phrasing like:

• "(Live) presumes (Spec)"
• "Verified (Live) requires Verified (Spec)"
• "A storyboard regression blocks Verified" (still true for (Spec); for (Live) the link is via the eight checks, not via (Spec))

4. attestation_verifier reporting/runner split

Once #3561 is implemented, every doc that mentions attestation_verifier should be checked: does it accurately say "reporting" rather than implying it covers all of (Live)? The note added in #3537 covers the primary doc; sweep for secondary ones.

5. Cross-link / anchor audit

When sections were renamed during the (Spec)/(Live) reframing, anchor links from other docs may have broken. Run the broken-links check after the sweep and confirm:

• #two-marks-... anchors removed from aao-verified.mdx are not still linked from elsewhere
• #why-these-two-marks-not-the-earlier-tier-1--tier-2 (currently in aao-verified.mdx) is still the canonical landing for "Why two marks?" cross-refs
• New sections added in docs(aao-verified): reconcile (Spec)/(Live) qualifier framing across spec docs + add 3 sections #3537 (#how-to-claim-each-qualifier, #what-aao-verified-is-not, #relationship-to-supporting-specs) have no broken inbound links

6. Storyboard / compliance-suite copy

The badge name is shown in the compliance heartbeat output, the storyboard runner CLI, and some of the lint rules. Audit:

• static/compliance/source/**/*.yaml — any prose referring to the mark by name
• scripts/lint-*.cjs — any error messages mentioning "AdCP Conformant" or old framings
• The @adcp/client storyboard runner output strings (separate repo, but worth flagging)

7. Changeset entries already queued for 3.1.0-beta

Six changesets in .changeset/ reference the mark. Grep:

grep -l 'AdCP Conformant\|Tier 1\|Tier 2\|AAO Verified mark' .changeset/*.md

Any hits should be updated to current framing — the release notes need to read consistently.

Acceptance

• A single sweep PR (or a small set of focused ones) that closes every hit from the audits above.
• Broken-links check passes.
• A reader landing on any of the affected pages cold sees one coherent framing: AAO Verified is one mark with two qualifiers (Spec) and (Live); they are independent axes; storyboards back (Spec); continuous observability backs (Live).
• No surviving "Tier 1 / Tier 2" or "AdCP Conformant + AAO Verified" two-marks language outside historical/changelog entries that explicitly describe the framing's evolution.

Out of scope

• Implementation (RFC: AAO Verified via canonical test campaigns (supersedes two-tier model in #2965) #3046 canonical-campaign runner, Define attestation_runner scope for AAO Verified (Live) canonical-campaign runner #3561 attestation_runner scope) — those land separately.
• New content beyond reconciliation — adding pages, expanding the (Live) checks, etc.
• Changes to any non-doc surface (schema descriptions are in scope as far as they're user-facing in spec docs; runtime code is out of scope).

Timeline

Ship before 3.1.0 GA so the release ships with a coherent doc set.

Related

• feat: AAO Verified agent badge system #2153 — initial (Spec)/(Live) reframing
• docs(aao-verified): make Live independent of Spec #3536 — independence clarification
• docs(aao-verified): reconcile (Spec)/(Live) qualifier framing across spec docs + add 3 sections #3537 — partial reconciliation
• Define attestation_runner scope for AAO Verified (Live) canonical-campaign runner #3561 — attestation_runner scope (separate, not blocking this sweep)
• RFC: AAO Verified via canonical test campaigns (supersedes two-tier model in #2965) #3046 — canonical-campaign runner RFC (separate)

[bokelley]

Triage

Classification: Doc sweep / consistency fix
Bucket(s): web / site / docs
Status: drafting-pr

What the experts said:

• docs-expert: non-breaking sweep with clear scope; "Two marks" heading confuses cold readers; ⊆ notation in conformance.mdx risks implying hierarchy; line 116 "presumes" is correctly about tenant isolation (not Spec/Live ordering) — leave it; no broken inbound anchor links.
• ad-tech-protocol-expert: framing change is non-breaking (no wire-format effect); salty-wasps-cheat.md changeset directly contradicts docs(aao-verified): make Live independent of Spec #3536 and is a pre-GA blocker; attestation_verifier scope binding should name the (Live) qualifier specifically; compliance YAML and lint scripts are clean.

My take: All hits are doc-only and non-breaking. Items 1–3, 5–7 executed in #3607. Item 4 (audit attestation_verifier docs once #3561 lands) stays open here.

Drafting PR #3607 covers:

• aao-verified.mdx: "Two marks" → "Naming history" section heading; fixes malformed 3-col table row
• conformance.mdx: replaces ⊆ notation with independence-first phrasing
• .changeset/salty-wasps-cheat.md: removes "Spec is a prerequisite for measuring Live" (contradicts docs(aao-verified): make Live independent of Spec #3536)
• .changeset/account-authorization-and-rbac-errors.md: qualifies attestation_verifier → AAO Verified (Live)

@adcp/client storyboard runner output strings are in a separate repo — flagged here for maintainer follow-up.

---

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

---

Generated by Claude Code