cowork-local/docs/instruction/agent/quality_gate.md

# 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.