docs: make the 3.2 media-buy lifecycle primary - #6642
Conversation
![aao-secretariat[bot]](https://avatars.githubusercontent.com/u/221690821?s=60&v=4){kind=small}
There was a problem hiding this comment.
Ladon verdict: Approve
Approve — docs-only reorganization with verified wire-shape fidelity.
This PR reorganizes the AdCP 3.2 compact media-buy lifecycle to be primary across navigation, concepts, the walkthrough, task reference, and design principles, and marks SDK 14.0.0-beta.0 status. It is documentation-only (12 files under docs/** plus docs.json and a changeset); no static/schemas/source/**, no server/**, and no dist/<semver>/ artifact files are touched.
Checks performed / cited by the reviewer:
- Every 3.2 wire-shape claim the prose introduces (list_products response versions, ProductDiscoveryCriteria, refine_proposals action/change_kind/constraints, accept_proposal proposal_terms_digest, control_media_buy revision, sync_creatives assignment_operations, media_buy.lifecycle_tools, REQUOTE_REQUIRED) was verified against
static/schemas/source/**and matches — no schema↔docs drift. - Changeset present and correctly patch-scoped; no released
dist/<semver>/artifact modified (immutability preserved). - No blocking or medium findings.
Decision-table walk: no critical/high findings (row 1 n/a). gated_paths is false (row 2 n/a). high_risk is true only via two (modified) docs/reference/** files, but no medium finding attaches to them, so rows 3–5 do not fire. No prior decision (row 6 n/a). No no-auto-approve team match (row 7 n/a). Zero medium findings (row 8 n/a). Falls through to row 9 → approve. The high_risk flag on modified reference docs is a look-closer signal only; the reviewer confirmed the changes preserve the wire contract.
There was a problem hiding this comment.
Ladon verdict: Comment (human reviewer recommended)
Comment — 2 medium findings, human review recommended.
Docs-only PR making the compact AdCP 3.2 media-buy lifecycle primary across discovery, lifecycle, task reference, design principles, and the main walkthrough. Wire examples verified schema-accurate, characters match specs/character-bible.md, the patch changeset is correctly scoped, and dist snapshot content is untouched (only mutable nav reorganized). No critical/high findings, no breaking-class change, no gated-paths trigger, no team gate.
Medium findings
- docs/media-buy/media-buys/index.mdx:72 — index.mdx rewrite orphans
#lifecycle-statesand#asynchronous-operationsanchors that four other pages still deep-link to - docs/media-buy/media-buys/lifecycle.mdx:69 — lifecycle.mdx Note links to an anchor this PR deletes
These are broken intra-doc anchors that will produce dead links for readers — worth fixing before merge, but not blocking. A human should confirm the anchor targets are restored or the deep-links updated.
Note on high_risk: true is driven only by (modified) entries under docs/reference/**; the reviewer found no medium-or-higher concern on those files, so the modification is presumed safe and does not trigger escalation.
Medium findings
- docs/media-buy/media-buys/index.mdx:72 — index.mdx rewrite orphans #lifecycle-states and #asynchronous-operations anchors
- docs/media-buy/media-buys/lifecycle.mdx:69 — lifecycle.mdx Note links to an anchor this PR deletes
There was a problem hiding this comment.
Ladon verdict: Approve
Approve — link-hygiene doc pass, both prior findings resolved.
This subsequent review addresses the two Medium findings from the prior comment decision:
- seller-integration.mdx now points to
#seller-implementation-invariants(real heading, diff L1564) — resolved. - lifecycle.mdx now points to
#state-machine(real heading, L1211) — resolved.
The reviewer confirms all newly-added cross-doc links resolve: the six task-reference/* targets exist, and compliance-catalog#error-code-requote-required matches the id emitted by generate-compliance-snippets.mjs:220 for REQUOTE_REQUIRED.
No current findings (none critical/high/medium). The high_risk flag is true only because several docs/reference/** files were modified, but the reviewer surfaced no medium-or-higher concern on any of them, so the modifications are presumed safe (row 5 does not fire without a medium finding). No schema changes, so schema↔docs coherence and changeset-scope gates are not implicated. Not a Breaking-class change. gated_paths is false and no no-auto-approve team match.
Decision table: rows 1–8 do not fire → row 9 approve. Net improvement over the prior comment run.
1 participant
Summary
The frozen 3.2.0-beta.0 snapshot content is unchanged; only its mutable navigation is reorganized.
Validation
Note on the local hook
The full server suite currently takes about 416 seconds, exceeding the pre-commit wrapper's 240-second ceiling. The wrapper timed out twice without an assertion failure; the same suite was then run unwrapped to completion before committing.