docs: publish release cadence policy + tighten red-team FAQ titles (#2312, #2313)#2359
Merged
docs: publish release cadence policy + tighten red-team FAQ titles (#2312, #2313)#2359
Conversation
…2312, #2313) Publishes a named release cadence so implementers can plan, closing the red-team "breaking change velocity contradicts stable standard" finding: - Minimum 18 months between majors (aligns with faq.mdx which already said 18mo–2yr; tightens the versioning.mdx range into a floor) - 4.0 target early 2027 - Minimum 12 months of security patches for the previous major after successor GA; CVE fixes only, no feature backports - Minimum 6 months deprecation notice before removal; windows do not reset when a deprecated feature is modified - v2 documented as the explicit exception to the 12-month commitment; future majors will not invoke this exception Cross-links versioning.mdx, roadmap.mdx, v2-sunset.mdx, and faq.mdx so the policy has one source of truth. Retitles two red-team FAQ accordions ("Is Scope3 getting preferential treatment?", "What if my buyer agent is compromised?") so a skeptical journalist searching the adversarial phrasing lands on the shipped answer (#2313). Deferred for a follow-up: definition-of-breaking rubric, canonical deprecations page, whats-new-in-v3 cadence footer. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
Schema Link Check ResultsCommit:
|
This was referenced Apr 19, 2026
This was referenced Apr 26, 2026
bokelley
added a commit
that referenced
this pull request
Apr 30, 2026
Security review: - MED: brand.json adcp_version asymmetry. /verification and /compliance both gate adcp_version through isValidAdcpVersionShape; brand.json emitted it raw. Fixed — now mirrored across all three surfaces. The DB CHECK is the actual gate, but brand.json is the public buyer- facing surface, so any future code path that bypasses the CHECK (raw SQL backfill, restored snapshot) MUST NOT leak through. - LOW: modes_by_role is a real footgun for buyers pinned to a specific AdCP version — they could read "spec+live" and infer the wrong contract for their version. Added a `deprecation_notice` field that ships alongside the data so long-tail crawlers see the warning without tracking release notes. Code review: - Schema gap: brand.json enrichment had no documented contract for the new badges[] array. Added an `AaoVerificationBlock` TS interface inline so future contributors don't drift the wire format. Strict type on the assignment so a missing field fails at compile time. - Comment wording: "first row per role is the highest" was misleading because roles can interleave in the SQL sort. Clarified the dedupe invariant. - Deprecation horizon: documented "≥6 months from this PR's merge per the cadence policy in #2359" alongside the "AdCP 4.0" target so buyer agents have a calendar reference rather than a moving version. Code review nit on extracting enrichAgentEntries to a module-level pure function for unit testing — agreed it's worth doing as a follow-up but didn't want to expand this PR's blast radius. Filing separately. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
bokelley
added a commit
that referenced
this pull request
Apr 30, 2026
stage 5) (#3604) * feat(verification): brand.json + /verification per-version detail (#3524 stage 5) Final stage of #3524. brand.json enrichment now includes a `badges[]` array — one entry per (role, adcp_version) with full per-version detail. Per Q6 of the resolved-decisions thread, this is the canonical forward-compat shape: adding future axes to a badge won't change the array. `roles[]` and `modes_by_role` stay as deprecated aliases for one release. Their values reflect "the current best mark" — highest- version badge per role. Clients reading them today keep working when parallel-version badges ship; new clients should read `badges[]` for the full picture. Removal target: AdCP 4.0. The /verification endpoint (decentralized public verifier surface) now includes adcp_version on each badge entry, validated through the same shape regex the /compliance endpoint uses. After this PR, #3524 is fully shipped. Deferred panel polish (role grouping, "show all versions" disclosure) tracked in #3603. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(verification): security + code review feedback on Stage 5 Security review: - MED: brand.json adcp_version asymmetry. /verification and /compliance both gate adcp_version through isValidAdcpVersionShape; brand.json emitted it raw. Fixed — now mirrored across all three surfaces. The DB CHECK is the actual gate, but brand.json is the public buyer- facing surface, so any future code path that bypasses the CHECK (raw SQL backfill, restored snapshot) MUST NOT leak through. - LOW: modes_by_role is a real footgun for buyers pinned to a specific AdCP version — they could read "spec+live" and infer the wrong contract for their version. Added a `deprecation_notice` field that ships alongside the data so long-tail crawlers see the warning without tracking release notes. Code review: - Schema gap: brand.json enrichment had no documented contract for the new badges[] array. Added an `AaoVerificationBlock` TS interface inline so future contributors don't drift the wire format. Strict type on the assignment so a missing field fails at compile time. - Comment wording: "first row per role is the highest" was misleading because roles can interleave in the SQL sort. Clarified the dedupe invariant. - Deprecation horizon: documented "≥6 months from this PR's merge per the cadence policy in #2359" alongside the "AdCP 4.0" target so buyer agents have a calendar reference rather than a moving version. Code review nit on extracting enrichAgentEntries to a module-level pure function for unit testing — agreed it's worth doing as a follow-up but didn't want to expand this PR's blast radius. Filing separately. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 3, 2026
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
1 participant
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
Closes the red-team "breaking change velocity contradicts stable standard" finding by publishing a named release cadence so implementers can plan (#2312), and tightens two FAQ accordion titles so a skeptical journalist searching the adversarial phrasing lands on the shipped answers (#2313 follow-up — the seven FAQ bodies already shipped in #2329).
Cadence policy (
docs/reference/versioning.mdx)Additions:
Cross-links
roadmap.mdx: v4.0 milestone heading gains the early-2027 target and links to the policy; dropped an inline restatement of the numbers so versioning.mdx is the single source of truthv2-sunset.mdx: back-link to the 12-month commitment section, naming v2 as the documented exceptionfaq.mdx:95: "How mature is the protocol?" updated to reflect the named policyRed-team FAQ titles (#2313)
Content was already shipped in #2329. Retitled two accordions so the adversarial search phrase in the issue actually matches:
Body text unchanged.
Expert review
Changes were reviewed by adtech-product, copywriter, and docs-expert subagents. Key applied feedback: tightened "1–2 years apart" → "minimum 18 months apart" (matches existing faq.mdx wording), trimmed marketing hedges from the cadence prose, rewrote the v2 exception paragraph to drop apologetic framing, dropped duplicated numbers from roadmap.mdx to prevent drift.
Two calls remain for maintainer judgment, not blocking this PR:
Deferred to follow-ups
whats-new-in-v3.mdxTest plan
npm run test:unit— 587 passnpm run typecheck— clean#release-cadence,#support-window-for-previous-major)docs/faq.mdx🤖 Generated with Claude Code