docs(agent): bổ sung role fix-dispatcher và siết lại bộ tài liệu agent

- Thêm agent/roles/0_fix_dispatcher.md: phân tier/lane cho từng defect trước khi các agent khác chạy, kèm agent/commands/fix.md và hợp đồng đầu ra agent/output/dispatch_plan.md. - Cập nhật system/guardrail, response_policy, security và các checklist ui/ux/pr_readiness cho khớp luồng mới. - Mở rộng knowledge: i18n_rules, screen_map, theme_tokens, secrets_and_config; cập nhật workflow intake_to_fix và handoff_contract. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-08 21:23:21 +09:00
parent fe99bc8727
commit 0efc4bbf0e
16 changed files with 5673 additions and 558 deletions
@@ -1,53 +1,158 @@
 # Checklist sẵn sàng tạo PR

-Dùng bởi `fix-implementer` (bước 9) và `regression-reviewer` (bước 8).
-Bám theo `.gitea/PULL_REQUEST_TEMPLATE.md` và `docs/governance/definition-of-done.md`.
+Checklist này được sử dụng bởi:

-## A. Cổng chất lượng
+* `fix-implementer` — kiểm tra ở bước 9.
+* `regression-reviewer` — kiểm tra ở bước 8.

- [ ] `python scripts/run_quality_gate.py` — xanh cả 5 cổng, **có dán output thật**.
- [ ] Gate C: `domain/`/`application/` không import PySide6/PyQt/`ui`/`app`.
- [ ] Gate A: không secret/plaintext mới.
- [ ] Gate S: không file nào > 400 LOC.
- [ ] Gate O: không module mồ côi (file mới đã được import trong cùng commit).
- [ ] Gate A/N: pytest xanh; test vốn đỏ từ trước được ghi riêng.
+Tham chiếu:

-## B. Kiểm chứng
+* `.gitea/PULL_REQUEST_TEMPLATE.md`
+* `docs/governance/definition-of-done.md`

- [ ] Test regression tồn tại và **đỏ trước / xanh sau**.
- [ ] Test chạy được headless (`QT_QPA_PLATFORM=offscreen`).
- [ ] Đã kiểm bằng mắt ở dark + light — hoặc ghi rõ "chưa kiểm chứng bằng mắt" kèm lý do.
- [ ] Đã kiểm ở các ngôn ngữ liên quan.
+---

-## C. Phạm vi & lịch sử
+## A. Kiểm tra chất lượng

- [ ] Một PR = một thay đổi logic. Không refactor lẫn vào.
- [ ] Không đổi format/indent toàn file; diff đọc được.
- [ ] Nhánh riêng, không commit thẳng `main`.
- [ ] Commit message nêu nguyên nhân gốc + `file:line` + issue.
- [ ] Không commit `.env`, `config.json` local, dữ liệu dưới `.cowork_local/`, `.venv`.
+* [ ] 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ế**.

-## D. Bảo mật
+* [ ] **Gate C:** Các thư mục `domain/` và `application/` không được import:
+  - `PySide6`
+  - `PyQt`
+  - `ui`
+  - `app`

- [ ] Không secret/PII/đường dẫn cá nhân trong code, test fixture, commit message, PR body.
- [ ] Ảnh chụp màn hình đính kèm đã được redact.
- [ ] Nếu chạm permission / credential / MCP write-exec / sandbox / network / TLS /
-      isolation / model routing / xoá dữ liệu → đánh dấu `security-review: required` và ghi
-      rõ trong PR rằng **CI xanh không đủ để merge**.
+* [ ] **Gate A:** Không tạo thêm secret hoặc thông tin nhạy cảm dạng plaintext.

-## E. Nội dung PR
+* [ ] **Gate S:** Không có file nào vượt quá **400 dòng code (LOC)**.

- [ ] Summary nói **tại sao**, không chỉ **cái gì**.
- [ ] Change Type đã tick.
- [ ] Scope: nêu rõ cả phần **cố ý không** làm.
- [ ] Validation: có lệnh và output thật.
- [ ] Security Impact: đã điền, kể cả khi là "không có".
- [ ] Compatibility: đã tick.
- [ ] Reviewer Notes: chỉ ra chỗ cần soi kỹ nhất.
- [ ] Tài liệu (`docs/`, ảnh `docs/screens/`) đã cập nhật nếu cần.
+* [ ] **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.

-## F. Ranh giớ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.

- [ ] Agent **không** tự merge, **không** tự đóng issue.
- [ ] Nếu là đóng góp của FSG AI Core: hiểu rằng chỉ "Done" khi PR đã merge vào Cowork Local,
-      kèm đủ core issue reference, PR, evidence, reviewer phía Cowork, merge reference.
+---
+
+## 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
+  ```