用途：指导在 Kibana 中实现和审查向后兼容的功能权限弃用，基于弃用权限映射框架。适用于重命名功能、拆分功能、合并功能、在功能与子功能权限间移动能力，以及审查相关 PR。
主要能力：通过 deprecated 属性标记冻结的旧功能（不在角色管理 UI 显示，但权限仍注册于 Elasticsearch）；用 replacedBy 将每个弃用权限映射到等价的新权限；采用惰性迁移，管理员通过 UI 保存角色时才替换旧权限。kibana_system 无法修改角色，这是驱动整体设计的安全约束。
使用方式：先注册新功能，再将旧功能标记为 deprecated（ID 必须保持不变，notice 需本地化并附文档链接）；在每个 all、read 及子功能权限上定义 replacedBy。无子功能时用简单数组形式；有子功能时顶层权限必须用 { default, minimal } 形式以区分 all 与 minimal_all。随后更新 API 权限、UI capabilities、告警消费者和 cases 所有者。启动时会校验：弃用功能每个权限必须有 replacedBy、非弃用功能不得有、引用的替换功能须存在且未弃用、替换权限须存在、启用权限不能被禁用权限替换等。
适用场景：功能重命名、拆分、合并、子功能提取、告警与 cases 连续性维护。
限制：角色不会自动迁移；需保证无权限提升或缩减，并确保零停机与回滚安全。具体代码示例可参考测试插件与 oss_features.ts，详细类型定义见 references/reference.md。