Deprecation & Migration

Gate Quyết Định 5 Bước

1. Tìm kiếm toàn bộ consumer: Bằng graph-first (search_graph → inbound trace_path → source snippet); fallback AST/Grep khi thiếu evidence.
2. Xác nhận replacement đã sẵn sàng: Đã tồn tại và được verify trên test case/fixture liên quan.
3. Phân loại tác động: Xác định migration là advisory hay bắt buộc, ảnh hưởng tương thích ngược và user-visible impact.
4. Đánh giá rủi ro Rollback & Data: Tuyệt đối cấm migration mang tính phá hủy (DROP/TRUNCATE) trên dữ liệu production. Destructive migration/data change, module boundary hoặc rollout/release change phải xin authority theo AGENTS.md.
5. Kế hoạch Rollout an toàn: Giữ compatibility adapter/flag khi cần coexistence giữa bản $N-1$ và $N$.

Không dùng số ngày, traffic %, age hay “zero usage” tùy ý. Threshold phải từ User, telemetry thật hoặc gate/rollout policy đã có.

Quy Trình Thực Thi

1. Đặt replacement sau seam hiện có; không tạo abstraction thừa cho một consumer đơn lẻ.
2. Migrate consumer theo thứ tự phụ thuộc (dependency order). Giữ compatibility adapter/flag chỉ khi có rollback hoặc coexistence need thật.
3. Test behavior song song khi cả old và new implementation còn hoạt động. Verify representative file/data và failure path, không chỉ compile.
4. Chỉ xóa old implementation khi trace không còn bất kỳ caller nào trong toàn bộ codebase và evidence rollout/telemetry đáp ứng threshold thật.
5. Xóa adapter/flag/test thừa khi chúng trở thành orphan. Xóa cả docs obsolete, trong cùng task; không xóa dead code không liên quan.

Trước khi thử lại hướng từng bị revert, đọc .agents/instincts.md và memory liên quan, rồi re-verify với code/docs hiện tại. Memory là cảnh báo, không phải bằng chứng runtime hiện tại.

Bàn giao gồm consumer đã migrate, compatibility còn lại, rollback path, checks đã chạy và residual.