cowork-local/agent/checklist/pr_readiness.md

# Checklist sẵn sàng tạo PR

Checklist này được sử dụng bởi:

* `fix-implementer` — kiểm tra ở bước 9.
* `regression-reviewer` — kiểm tra ở bước 8.

Tham chiếu:

* `.gitea/PULL_REQUEST_TEMPLATE.md`
* `docs/governance/definition-of-done.md`

---

## A. Kiểm tra chất lượng

* [ ] Chạy `python scripts/run_quality_gate.py`.
  Cả **5 quality gate đều phải PASS** và phải ghi lại **output thực tế**.

* [ ] **Gate C:** Các thư mục `domain/` và `application/` không được import:
  - `PySide6`
  - `PyQt`
  - `ui`
  - `app`

* [ ] **Gate A:** Không tạo thêm secret hoặc thông tin nhạy cảm dạng plaintext.

* [ ] **Gate S:** Không có file nào vượt quá **400 dòng code (LOC)**.

* [ ] **Gate O:** Không có file/module mới bị bỏ quên.
  File Python mới phải được sử dụng/import trong cùng thay đổi.

* [ ] **Gate A/N:** Test phải PASS.
  Nếu đã có test FAIL từ trước thì phải ghi rõ đó là **lỗi có sẵn**, không phải lỗi do bản sửa này gây ra.

---

## B. Kiểm tra bản sửa

* [ ] Có **regression test** cho lỗi đã sửa.

* [ ] Regression test phải chứng minh được:
  - **Trước khi sửa:** test FAIL.
  - **Sau khi sửa:** test PASS.

* [ ] Test chạy được ở chế độ headless:
  `QT_QPA_PLATFORM=offscreen`

* [ ] Nếu thay đổi liên quan đến UI:
  - Đã kiểm tra giao diện ở **Dark Mode**.
  - Đã kiểm tra giao diện ở **Light Mode**.
  - Nếu chưa thể kiểm tra bằng mắt, phải ghi rõ:
  **"Chưa kiểm chứng bằng mắt"** và nêu lý do.

* [ ] Nếu thay đổi liên quan đến ngôn ngữ:
  đã kiểm tra các ngôn ngữ bị ảnh hưởng.

---

## C. Kiểm tra phạm vi thay đổi và Git

* [ ] Một PR chỉ giải quyết **một thay đổi logic chính**.
  Không đưa refactor không liên quan vào cùng PR.

* [ ] Không tự ý format hoặc thay đổi indent của toàn bộ file.
  Diff phải rõ ràng và dễ review.

* [ ] Làm việc trên **branch riêng**.
  Không commit trực tiếp vào `main`.

* [ ] Commit message phải nêu:
  - Nguyên nhân gốc của lỗi.
  - Vị trí code liên quan (`file:line`).
  - Issue liên quan.

* [ ] Không commit các file/dữ liệu sau:
  - `.env`
  - `config.json` local
  - `.cowork_local/`
  - `.venv/`

---

## D. Kiểm tra bảo mật

* [ ] Không có các thông tin sau trong code, test fixture, commit message hoặc PR body:
  - Secret
  - PII/thông tin cá nhân
  - Đường dẫn chứa thông tin cá nhân trên máy local

* [ ] Nếu có ảnh chụp màn hình trong PR:
  đã che (redact) toàn bộ thông tin nhạy cảm trước khi đính kèm.

* [ ] Nếu thay đổi liên quan đến một trong các nội dung sau:

  ```
  - Permission/quyền truy cập
  - Credential/thông tin xác thực
  - MCP write/exec
  - Sandbox
  - Network
  - TLS
  - Isolation
  - Model routing
  - Xóa dữ liệu

  thì phải:

  1. Đặt `security-review: required`.
  2. Ghi rõ trong PR rằng:
     **"CI xanh không có nghĩa là có thể merge ngay."**
  3. Chờ security review theo quy trình trước khi merge.
  ```

---

## E. Kiểm tra nội dung PR

* [ ] **Summary** phải giải thích **tại sao cần sửa**, không chỉ mô tả đã sửa cái gì.

* [ ] Đã chọn **Change Type** phù hợp.

* [ ] **Scope** phải ghi rõ:
  - Những gì đã thay đổi.
  - Những gì **cố ý không thay đổi**.

* [ ] **Validation** phải ghi:
  - Lệnh đã chạy.
  - Kết quả thực tế/output.

* [ ] **Security Impact** phải được điền.
  Nếu không ảnh hưởng bảo mật, ghi rõ **"Không có"**.

* [ ] Đã chọn **Compatibility** phù hợp.

* [ ] **Reviewer Notes** phải chỉ ra những phần reviewer cần kiểm tra kỹ nhất.

* [ ] Đã cập nhật tài liệu nếu cần:
  - `docs/`
  - Ảnh màn hình trong `docs/screens/`

---

## F. Giới hạn quyền của Agent

* [ ] Agent **không được tự merge PR**.

* [ ] Agent **không được tự đóng issue**.

* [ ] Nếu đây là đóng góp từ **FSG AI Core**, cần hiểu rằng trạng thái **"Done"** chỉ được xác nhận khi PR đã thực sự được merge vào Cowork Local và có đầy đủ:

  ```
  - Core issue reference
  - PR reference
  - Evidence
  - Reviewer phía Cowork
  - Merge reference
  ```