docs: add code/layout fix agent instruction modules and skill

Add a 7-module instruction set for an agent that fixes bugs and UI/layout
defects (role, task, input contract, process, output contract, quality gate,
examples) under docs/instruction/agent/, plus a condensed skill_library entry
so the app can load it from the Skill Manager.

The modules encode the working principles this project expects: understand the
code first, fix the root cause rather than the symptom, keep the diff minimal,
change no behavior outside the requirement, follow the existing architecture
(ADR-001 4-tier layering) and patterns, and judge changes on compatibility,
security, maintainability and testability. Unresolved points must be recorded
as Assumption, Open Question or Limitation instead of being decided silently.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/instruction/agent/quality_gate.md

@@ -0,0 +1,126 @@
+# quality_gate.md — Checklist kiểm soát chất lượng
+
+> Trách nhiệm của file này: định nghĩa **checklist self-review** agent phải chạy ở Step 6
+> của `process.md`, cách tính điểm và ngưỡng pass.
+> Đây là file có ưu tiên cao nhất — không được đánh đổi vì lý do thời gian hay vì "sửa nhỏ".
+
+## 1. Cách sử dụng
+
+1. Chạy lần lượt 7 nhóm checklist dưới đây, đánh `Pass` / `Fail` cho từng mục.
+2. Mục `Fail` → **sửa ngay**, không ghi "sẽ bổ sung sau".
+3. Chạy lại checklist. Lặp tối đa **2 lần**.
+4. Sau 2 lần vẫn `Fail` vì thiếu thông tin bên ngoài → chuyển thành Open Question (`OQ-xx`).
+5. Tính điểm theo §3. Chưa đạt ngưỡng thì **không được trả kết quả**.
+
+Nhóm áp dụng theo chế độ: **G5 chỉ áp dụng cho LAYOUT_FIX và MIXED**.
+Với CODE_FIX thuần, bỏ G5 và chia lại điểm theo §3.
+
+---
+
+## 2. Checklist
+
+### G1. Root cause — Sửa đúng nguyên nhân, không che triệu chứng
+
+- [ ] Nguyên nhân gốc được nêu cụ thể tới `file:line`, không phải phỏng đoán ("có lẽ do...").
+- [ ] Nguyên nhân gốc giải thích được **toàn bộ** triệu chứng đã quan sát, không sót phần nào.
+- [ ] Không có `try/except` nuốt lỗi hay kiểm tra null được thêm vào chỉ để hết crash.
+- [ ] Không sửa nhiều chỗ cùng lúc theo kiểu thử-xem-cái-nào-ăn.
+
+### G2. Minimal & scoped diff — Diff nhỏ và đúng phạm vi
+
+- [ ] Mỗi file trong diff đều có lý do rõ ràng trong section Changes.
+- [ ] Không có drive-by cleanup: đổi tên biến, sắp xếp lại import, format lại file ngoài vùng sửa.
+- [ ] Không có refactor kiến trúc kèm theo trong cùng lần fix.
+- [ ] Không thêm dependency mới.
+- [ ] Không đổi public API / signature mà nơi khác đang gọi (trừ khi yêu cầu nói rõ).
+- [ ] Không xoá code chưa hiểu rõ mục đích.
+
+### G3. Convention & consistency — Bám chuẩn codebase
+
+- [ ] Style của đoạn sửa khớp với file xung quanh (đặt tên, type hint, comment, thứ tự import).
+- [ ] Ngôn ngữ comment / docstring giữ đúng như file gốc.
+- [ ] Không có mã màu rời rạc trong widget; màu đi qua `theme/palettes.py`.
+- [ ] Không có `setStyleSheet` cục bộ chồng lên thứ `theme/qss.py` đã định nghĩa.
+- [ ] Sửa đúng tầng theo bảng ở `process.md` Step 3.4 (layout code / qss / palette).
+- [ ] Không còn code debug tạm: lệnh in tạm, log tạm, comment kiểu "sẽ sửa sau".
+
+### G4. Correctness & regression — Đúng và không phá thứ khác
+
+- [ ] Hành vi mong đợi đã được kiểm chứng thật, không phải suy đoán.
+- [ ] Sửa logic → có test hồi quy **fail trước khi sửa** và **pass sau khi sửa**
+      (hoặc nêu rõ vì sao không viết được test).
+- [ ] Đã chạy test liên quan; kết quả được ghi **nguyên văn**, kể cả khi fail.
+- [ ] Đã rà mọi nơi khác đang dùng thứ vừa sửa (hàm, widget, selector, token) và kết luận.
+- [ ] Không có test nào bị nới lỏng assert để pass.
+- [ ] Edge case liên quan đã được xét: giá trị rỗng, null, danh sách trống, dữ liệu rất dài.
+
+### G5. Layout robustness — Chỉ áp dụng LAYOUT_FIX / MIXED
+
+- [ ] Đã kiểm ở tối thiểu 2 kích thước cửa sổ, gồm cả kích thước nhỏ nhất còn dùng được.
+- [ ] Đã kiểm cả theme **sáng** và **tối**.
+- [ ] Đã kiểm với nội dung text dài bất thường: không tràn, không chồng, không cắt chữ.
+- [ ] Đã kiểm trạng thái rỗng, nếu widget hiển thị danh sách.
+- [ ] Không dùng kích thước cứng để ép cho vừa; nếu buộc phải dùng, đã nêu lý do.
+- [ ] Widget vẫn co giãn đúng khi cửa sổ đổi kích thước (layout và size policy,
+      không phải toạ độ tuyệt đối).
+- [ ] Thay đổi trên selector dùng chung đã được kiểm ở các widget khác cùng dùng selector đó.
+
+### G6. Safety — An toàn
+
+- [ ] Không có credential, token, API key, connection string trong code, log, test hay report.
+- [ ] Không có dữ liệu cá nhân thật trong test fixture hay ví dụ.
+- [ ] Không thêm log ghi ra dữ liệu nhạy cảm.
+- [ ] Vùng critical trong `SECURITY.md` không bị chạm; nếu buộc phải chạm,
+      đã nêu rõ và xin xác nhận.
+- [ ] Không tự `git commit`, `git push` hay tạo pull request khi người dùng chưa yêu cầu.
+
+### G7. Reviewability — Sẵn sàng cho người khác review
+
+- [ ] Fix Report đủ section theo `output_contract.md`, không section nào bị bỏ trắng.
+- [ ] Reviewer không cần hỏi lại: nguyên nhân gốc là gì, sửa ở đâu, đã kiểm thế nào,
+      có phá gì không.
+- [ ] Mỗi thay đổi (`CH-xx`) nối được về nguyên nhân gốc hoặc về một `AS-xx`.
+- [ ] Mọi Open Question đều cụ thể, có người cần trả lời và có `Blocking`.
+- [ ] Mọi Assumption đều nêu tác động nếu giả định sai.
+- [ ] Điểm không giải quyết được đã ghi thành Limitation (`LM-xx`) — không bị bỏ qua im lặng,
+      không trình bày như đã trọn vẹn, và không có quyết định nghiệp vụ nào do agent tự chốt.
+- [ ] Không còn placeholder kiểu `TBD`, `???`, `sẽ bổ sung sau`.
+- [ ] Có đề xuất commit message theo Conventional Commit.
+
+---
+
+## 3. Scoring & Ngưỡng pass
+
+| Nhóm | Tiêu chí | Điểm (LAYOUT_FIX / MIXED) | Điểm (CODE_FIX thuần) |
+|---|---|---|---|
+| G1 | Root cause | 25 | 30 |
+| G2 | Minimal & scoped diff | 15 | 20 |
+| G3 | Convention & consistency | 10 | 10 |
+| G4 | Correctness & regression | 20 | 25 |
+| G5 | Layout robustness | 15 | — |
+| G6 | Safety | 10 | 10 |
+| G7 | Reviewability | 5 | 5 |
+| | **Tổng** | **100** | **100** |
+
+Điểm mỗi nhóm = `(số mục Pass / tổng số mục) × điểm tối đa của nhóm`, làm tròn xuống.
+
+| Tổng điểm | Kết luận | Hành động |
+|---|---|---|
+| ≥ 85 | Pass | Được trả kết quả |
+| 70 - 84 | Conditional | Sửa các mục Fail rồi chạy lại checklist |
+| < 70 | Fail | Quay lại `process.md` từ Step 2, làm lại phân tích |
+
+## 4. Điều kiện chặn tuyệt đối
+
+Bất kể tổng điểm bao nhiêu, **không được trả kết quả** nếu vi phạm bất kỳ điều nào sau:
+
+1. **Chưa xác định được nguyên nhân gốc** mà vẫn sửa code.
+2. **Nhóm G6 Safety có bất kỳ mục Fail.**
+3. **Báo test pass mà không thực sự chạy test**, hoặc che kết quả fail.
+4. **Nới lỏng assert của test** để test pass.
+5. **Diff chạm file không giải thích được lý do.**
+6. Còn credential hoặc dữ liệu cá nhân thật trong code, test hay report.
+7. Đã tự commit / push / tạo pull request khi người dùng không yêu cầu.
+
+Vi phạm điều 1 → dùng khối `Root Cause Not Confirmed` trong `output_contract.md` §6
+thay vì trả bản sửa.