api-deprecation-plannerlisted

Retire an interface through measured migration, not a deletion date alone. ## Workflow 1. **Define the retiring surface.** Identify endpoints, methods, fields, event versions, SDK methods, agent tools, error codes, authentication modes, and undocumented behaviors consumers may rely on. 2. **Inventory consumers.** Combine gateway logs, client identifiers, tracing, repository search, SDK telemetry, support records, partner contracts, and owner interviews. State blind spots and the observation window. 3. **Verify the replacement.** Map every required behavior, performance property, permission, error, and operational dependency to the replacement. Record gaps and migration prerequisites. 4. **Set policy and timeline.** Apply versioning commitments, contractual notice, client release cadence, and rare usage cycles. Define announcement, warning, migration, freeze, disablement, and deletion milestones with owners. 5. **Make deprecation observable.** Add safe usage metrics, per-consumer attribution where allowed, structured warnings, response headers or schema directives, dashboards, and alerts for unexpected traffic changes. 6. **Support migration.** Provide side-by-side examples, SDK or codemod support, test environments, compatibility checks, and escalation paths. Avoid telling consumers only that the old interface will disappear. 7. **Define exit criteria.** Require replacement parity, acknowledged high-risk consumers, traffic below a justified threshold for a representative wi