VOCV2 Hardening Update Summary

• Update date: 2026-02-09
• Revised date: 2026-03-02
• Scope: Option A - SoT Hardening + Patch mâu thuẫn chính cho VocabV2
• Owner: Documentation hardening pass

1. Mục tiêu update

• Tạo một Source of Truth (SoT) để chốt rule vận hành.
• Đồng bộ các tài liệu core/downstream đang mâu thuẫn về batching, mixing, tiering, writing difficulty, đơn vị D/K, cryo comeback, và recap closing loop.

2. Kết quả chính

2.1 SoT mới được tạo

• Core Logic/VOCV2_Product_Spec_Hardening_v1.md

Tài liệu này chốt:

• Session config contract (micro-batch 5, preload web/mobile, prefetch, debt threshold, guardrails, cryo, penalty).
• Tier contract float-safe (failCount theo range).
• New item contract theo unseen (không dựa vào F=0).
• Mixing contract A/B/C + mix cycle 10 items cho target 30/70.
• Writing contract cập nhật theo catalog thực tế: Writing HARD-only, level thấp dùng lớp đệm Reading/Speaking/Listening.
• Time unit contract: D theo phút, K=2400 phút.
• Cryo comeback có 50/50 diagnostic.
• Recap quick-fix CTA.
• QA acceptance checklist.

2.2 Các mâu thuẫn chính đã được xử lý

1. Batch/mix mâu thuẫn (5-10, 3-2, 60/40, 30/70) -> chuẩn hóa theo SoT.
2. Tiering với failCount số thực -> đổi sang điều kiện range float-safe.
3. Nhầm New vs Withered qua F=0 -> New dùng unseen.
4. Xung đột Safety Gate vs Writing HARD-only -> chuyển sang cơ chế lớp đệm Reading/Speaking/Listening ở level thấp.
5. Lệch đơn vị D/K và ví dụ legacy /200 -> chuẩn hóa theo phút, K=2400.
6. Cryo chỉ momentum -> thêm diagnostic 50/50.
7. Recap có closing-loop nhưng thiếu đường sửa sai nhẹ -> thêm CTA quick-fix.
8. Content QA/fallback chưa chặt -> thêm contract publish + fallback.

3. Danh sách file đã cập nhật

3.1 Core logic / UX flow / UI mapping

• Core Logic/VOCV2_Product_Spec_Hardening_v1.md (new)
• Core Logic/VOCV2_Data_Model.md
• Core Logic/VOCV2_Item_Prioritization_Logic.md
• Core Logic/VOCV2_Exercise_Types.md
• Core Logic/VOCV2_Mechanism_Exlpained.md
• Core Logic/VOCV2_Content_Generation_Strategy.md
• UX Flows/VOCV2_Session_Flow.md
• UX Flows/VOCV2_Session_Recap_Suggestion.md
• UX Flows/VOCV2_Session_Sample_Experience.md
• UI Logic Mapping/VOCV2_UILM_Recommendation_Engine.md
• UI Logic Mapping/VOCV2_UILM_Item_Visuals.md
• VOCv2_00_Overview.md
• VOCV2_Mechanism_CheatSheet.md

3.2 Downstream/context

• docs/Domains/DOL English/Feature Package/FEATURE_Vocab_v2.md
• docs/context/vocab.mdc
• Business Logic/VOCV2_Analytics.md (sync event/metric taxonomy theo hardening)

4. Quy ước sau update

• Nếu có mâu thuẫn giữa docs, ưu tiên:
  1. Core Logic/VOCV2_Product_Spec_Hardening_v1.md
  2. Các core docs đã được gắn Hardening Note
  3. Các docs downstream

5. Kiểm tra sau cập nhật

• Đã chạy consistency pass bằng rg cho các pattern mâu thuẫn chính trong cụm tài liệu core/UI flow.
• Không chỉnh prototype HTML.
• Không mở rộng phạm vi sang gamification/leaderboard implementation.

6. Ghi chú

• Update này là hardening tài liệu, không thay đổi mã nguồn runtime.
• Một số file không liên quan thuộc khu vực Design System có thay đổi độc lập và không nằm trong scope VocabV2.