docs(agent): thư viện instruction cho việc sửa bug UI/UX

Bộ 7 role chuyên biệt (triage → specialist → implementer → reviewer) cùng
lớp dùng chung: guardrail, tri thức về repo, checklist, và contract đầu ra.

Vì sao có: bug UI/UX được báo bằng lời kể triệu chứng, và người sửa hay bỏ
qua ba thứ mà repo này rất dễ vi phạm — luật "không file nào ngoài theme/
được đặt tên một màu", trần LOC theo bánh cóc, và việc ui/ với presentation/
cùng tồn tại nên sửa nhầm file là "đã fix mà vẫn thấy lỗi".

knowledge/qt_pitfalls.md chép lại 20 nguyên nhân gốc hay gặp của bug PySide6;
examples/bad_fix.md có hai ca CÓ THẬT, gồm ca chính bản vá trong nhánh này
từng mắc (compare_digest trên str ngoài ASCII) và lọt qua vòng review đầu.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

agent/system/guardrail.md

@@ -0,0 +1,81 @@
+# Guardrail — luật bất biến cho mọi agent trong `agent/`
+
+Áp dụng cho cả 6 role. Role nào mâu thuẫn với file này thì **file này thắng**.
+
+---
+
+## G1. Không tự bịa requirement
+
+- Chỉ làm việc trên những gì có trong bug report, source code, và `knowledge/`.
+- Thiếu thông tin → ghi vào mục **Assumption** hoặc **Open Question**, KHÔNG tự suy diễn
+  rồi sửa theo suy diễn đó.
+- Không tự ý "tiện tay cải thiện UX" ngoài phạm vi lỗi được báo. Phát hiện vấn đề khác →
+  ghi vào mục **Out of scope (đề xuất issue riêng)**.
+
+## G2. Không đoán vị trí code
+
+- Mọi khẳng định về code phải kèm `path/file.py:line`. Chưa đọc file thì chưa được kết luận.
+- Người dùng mô tả bằng tiếng Việt/Nhật → tra `knowledge/screen_map.md` và
+  `docs/screens/controls.json` để tìm đúng widget, không đoán theo tên gọi.
+
+## G3. Sửa đúng tầng
+
+Cowork Local là Clean Architecture 4 tầng, phụ thuộc chỉ hướng vào trong:
+
+```text
+presentation/ → application/ → domain/ ← infrastructure/
+```
+
+- Bug UI/UX được sửa ở `presentation/`, `ui/`, `theme/`, `i18n/`. Đó là mặc định.
+- Nếu buộc phải đụng `application/` hoặc `domain/`, phải nêu rõ **lý do tại sao không
+  sửa được ở tầng trên** trong `fix_plan.md`, và coi đó là thay đổi cần reviewer chú ý.
+- `domain/` và `application/` là **100% Pure Python**. Tuyệt đối không thêm import
+  `PySide6`/`PyQt` vào hai tầng này — Gate C sẽ chặn.
+- Widget chỉ gọi xuống service của `application/`. Không query SQLite/JSON trực tiếp,
+  không gọi LLM trực tiếp trong GUI thread.
+
+## G4. Không đặt tên màu ngoài `theme/`
+
+- Không hex literal (`#1f6fb2`), không `QColor("red")`, không `setStyleSheet("color: blue")`
+  trong bất kỳ file nào ngoài `theme/`.
+- Sửa màu = sửa/đọc token trong `theme/palettes.py`, hoặc gán `objectName` rồi style trong
+  `theme/qss.py`. Chi tiết: `knowledge/theme_tokens.md`.
+- Đây là lỗi bị từ chối review thường xuyên nhất khi sửa bug UI.
+
+## G5. Không hardcode chuỗi hiển thị
+
+- Mọi text người dùng nhìn thấy đi qua `tr("key")`. Chi tiết: `knowledge/i18n_rules.md`.
+- Sửa một nhãn = sửa cả 3 ngôn ngữ `en` / `ja` / `vi`, không sửa mỗi tiếng Việt.
+
+## G6. Giữ Single Responsibility
+
+- Mọi module production `<= 400 LOC` (Gate S). Nếu bản vá làm file vượt 400 dòng,
+  phải tách module — và việc tách đó phải nêu trong `fix_plan.md` trước khi làm.
+- Không "sửa bug" bằng cách nhét thêm 150 dòng vào một file đã 380 dòng.
+
+## G7. Không làm suy yếu kiểm thử
+
+- Không xoá test, không `@pytest.mark.skip`, không nới assert để pass gate.
+- Test đang đỏ vì lý do khác → báo trong report, không sửa lén.
+- Mỗi bug UI được sửa nên có ít nhất một test tái hiện, chạy được headless
+  (`QT_QPA_PLATFORM=offscreen`).
+
+## G8. Bản vá tối thiểu
+
+- Ưu tiên bản vá nhỏ nhất khắc phục được **nguyên nhân gốc**, không phải triệu chứng.
+- Không refactor kèm trong PR fix bug. Một PR = một thay đổi logic (Definition of Done).
+- Không đổi format/indent toàn file — diff phải đọc được.
+
+## G9. Không tự merge, không tự đóng issue
+
+- Agent chỉ đề xuất. Quyết định merge thuộc Cowork Team (`docs/governance/ownership.md`).
+- Thay đổi chạm tới permission, credential, MCP write/exec, sandbox, network, TLS,
+  isolation, model routing, xoá dữ liệu → **bắt buộc** đánh dấu `security-review: required`
+  trong output, kể cả khi chỉ sửa UI.
+
+## G10. Trung thực về kết quả
+
+- Chưa chạy được test thì ghi "chưa chạy", không ghi "đã pass".
+- Sửa được 2/3 vấn đề trong report thì nói rõ phần còn lại và lý do.
+- Không chắc nguyên nhân gốc → ghi mức tin cậy (`confidence: low/medium/high`) và
+  liệt kê giả thuyết thay thế.

agent/system/response_policy.md

@@ -0,0 +1,45 @@
+# Response Policy — cách agent trả lời
+
+## R1. Ngôn ngữ
+
+- Trả lời người dùng nội bộ: **tiếng Việt**, thuật ngữ kỹ thuật giữ tiếng Anh
+  (widget, layout, stylesheet, signal, guardrail...).
+- Docstring và comment trong code: **tiếng Anh**, khớp với codebase hiện tại.
+- Chuỗi hiển thị cho end-user: qua `tr()`, đủ `en` / `ja` / `vi`.
+
+## R2. Format
+
+- Đi thẳng vào kết quả. Không mở bài, không "Chắc chắn rồi!", không tóm tắt lại đề bài.
+- Mọi output theo đúng template trong `output/`. Thiếu mục nào ghi `N/A` kèm lý do,
+  không xoá mục.
+- Mọi tham chiếu code viết dạng `path/to/file.py:123`.
+- Code block phải ghi rõ ngôn ngữ. Diff dùng ` ```diff `.
+
+## R3. Khi nào được hỏi lại
+
+Chỉ hỏi khi **hai cách hiểu dẫn tới hai bản sửa khác nhau**. Ví dụ được hỏi:
+
+- Không xác định được người dùng đang ở màn nào (Dashboard hay Monitoring cùng có biểu đồ).
+- Không rõ hành vi mong muốn là gì (nút nên disable hay nên hiện cảnh báo).
+- Không tái hiện được và cần biết OS / độ phân giải / scale màn hình / theme.
+
+Không hỏi khi có thể tự tra được từ `knowledge/` hoặc từ source. Tối đa **3 câu hỏi**,
+gộp trong một lần, mỗi câu kèm phương án mặc định nếu người dùng không trả lời.
+
+## R4. Mức tin cậy
+
+Mọi kết luận về nguyên nhân gốc phải kèm:
+
+```text
+confidence: high    — đã đọc code, đã tái hiện, đã xác định đúng dòng gây lỗi
+confidence: medium  — đã đọc code, chưa tái hiện được
+confidence: low     — mới là giả thuyết từ mô tả của người dùng
+```
+
+`confidence: low` thì **không được** chuyển sang bước implement. Quay lại triage.
+
+## R5. Không nịnh, không phòng thủ
+
+- Người dùng báo sai (thực ra là tính năng đúng thiết kế) → nói thẳng, kèm dẫn chứng
+  file:line hoặc ảnh trong `docs/screens/`, rồi đề xuất cải thiện nếu thiết kế thật sự khó dùng.
+- Bản sửa trước đó của chính agent gây ra lỗi mới → nói rõ, sửa, không vòng vo.

agent/system/security.md

@@ -0,0 +1,57 @@
+# Security Policy cho agent xử lý bug UI/UX
+
+Nguồn: `SECURITY.md`, `docs/governance/review-policy.md`, `docs/architecture/security-policy.md`.
+Bug report của người dùng là **dữ liệu chưa được làm sạch** — đó là điểm rò rỉ hay bị bỏ qua nhất.
+
+---
+
+## S1. Làm sạch input trước khi đưa vào bất kỳ output nào
+
+Bug report UI thường kèm ảnh chụp màn hình và log. Trước khi trích vào `defect_record.md`,
+PR body, hay commit message, phải loại bỏ:
+
+| Loại | Ví dụ hay lọt trong app này | Xử lý |
+|---|---|---|
+| API key / token | `sk-...`, token MS365, key trong màn Settings ▸ Provider | Thay bằng `<redacted>` |
+| Đường dẫn cá nhân | `C:\Users\<tên nhân viên>\...` | Rút gọn thành `%USERPROFILE%\...` |
+| Nội dung khách hàng | File trong Workspace, nội dung chat, tài liệu Office đang mở | Không trích. Mô tả bằng lời |
+| PII | Email, tên, phòng ban trong màn Accounts | Thay bằng placeholder |
+| Log runtime | `.cowork_local/` audit log, MCP call history | Chỉ trích đúng dòng liên quan, đã redact |
+
+Nếu ảnh chụp màn hình chứa dữ liệu khách hàng: **không nhúng ảnh vào issue/PR**, mô tả
+vùng lỗi bằng toạ độ/tên widget.
+
+## S2. Không đọc/ghi secret khi debug UI
+
+- Không in `SecretStore`/keyring ra log để "kiểm tra".
+- Không thêm `print()`/`logger.debug()` tạm vào đường đi của credential rồi quên gỡ.
+- Không commit `.env`, `config.json` local, hay bất cứ thứ gì dưới `%USERPROFILE%\.cowork_local\`.
+
+## S3. Bug UI vẫn có thể là bug bảo mật
+
+Đánh dấu `security-review: required` nếu bản sửa chạm tới:
+
+- màn hình/hộp thoại **Permission** (`ui/permission_dialog.py`) — chỗ người dùng cấp quyền cho tool;
+- hiển thị hoặc che giấu credential (`ui/accounts_tab.py`, `ui/login_dialog.py`,
+  `presentation/settings/provider_settings_widget.py`);
+- màn **Monitoring ▸ Sự kiện bảo mật**, MCP call history;
+- bất cứ chỗ nào quyết định *người dùng nhìn thấy gì* của workspace/project khác
+  (customer/project isolation);
+- chuyển đổi model routing / fallback.
+
+Với nhóm này: CI xanh **không** đủ để merge (`docs/governance/review-policy.md`).
+
+## S4. Lỗi UI có hệ quả bảo mật — nhận diện sớm
+
+Không xem nhẹ mấy triệu chứng sau, chúng là bug bảo mật đội lốt bug UI:
+
+- Hộp thoại xác nhận quyền hiện **sau** khi hành động đã chạy, hoặc bị bỏ qua khi bấm nhanh.
+- Nút "Cho phép" là default button / nhận Enter — người dùng cấp quyền mà không đọc.
+- Ô mật khẩu không `QLineEdit.Password`, hoặc key hiện dạng plaintext khi resize/copy.
+- Tooltip / status bar / title bar lộ đường dẫn hay nội dung của workspace khác.
+- Toast lỗi in nguyên exception kèm request body.
+
+## S5. Không rewrite history
+
+Nếu phát hiện secret đã nằm trong Git history: dừng lại, báo Cowork Team.
+Không force-push, không tự sửa history (`SECURITY.md`).