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/workflow/handoff_contract.md

@@ -0,0 +1,52 @@
+# Handoff Contract — envelope truyền giữa các agent
+
+Mọi agent kết thúc lượt bằng khối YAML này, đặt **ngay trên** phần nội dung chính.
+Đây là phần máy đọc; phần dưới nó là phần người đọc.
+
+```yaml
+---
+defect_id: UI-2026-0907-01        # UI-<YYYYMMDD>-<số thứ tự trong ngày>
+from_agent: ui-bug-triage
+next_agent: ui-visual-fixer       # xem bảng giá trị hợp lệ bên dưới
+category: visual                  # visual | flow | i18n-a11y | security | not-ui
+severity: S2                      # S1 | S2 | S3 | S4
+confidence: high                  # low | medium | high
+reproducible: yes                 # yes | no | intermittent
+security_review: not-required     # required | not-required
+affected_files:
+  - presentation/folder/folder_tab.py:118
+  - theme/qss.py:204
+themes_verified: [dark, light]    # [] nếu chưa kiểm
+languages_verified: [vi]          # [] nếu không liên quan
+blocked_on: []                    # danh sách open question CHẶN bước tiếp theo
+---
+```
+
+## Giá trị hợp lệ của `next_agent`
+
+| Giá trị | Nghĩa |
+|---|---|
+| `ui-visual-fixer` / `ux-flow-fixer` / `i18n-a11y-fixer` | Route sang specialist UI |
+| `security-defect-fixer` | Route sang specialist bảo mật (`category: security`) |
+| `fix-implementer` | Plan đã sẵn sàng để hiện thực |
+| `regression-reviewer` | Patch đã sẵn sàng để review |
+| `HUMAN_REVIEW` | Xong phía agent; chờ Cowork Team |
+| `RETURN_TO_REPORTER` | Không phải bug, hoặc thiếu thông tin chặn, hoặc cần quyết định sản phẩm |
+
+## Luật
+
+1. **`defect_id` không đổi** suốt vòng đời một lỗi, kể cả khi quay vòng FAIL.
+2. Một defect_record = **một nguyên nhân gốc**. Triage phát hiện hai nguyên nhân → tách
+   thành hai `defect_id`.
+3. `confidence: low` → `next_agent` chỉ được là `ui-bug-triage` hoặc `RETURN_TO_REPORTER`.
+4. `blocked_on` khác rỗng → agent nhận **không** được implement; chỉ được điều tra thêm.
+5. `security_review: required` là **cờ dính**: một khi bật, không agent nào được tắt.
+   Chỉ Cowork Team gỡ được. `category: security` thì cờ này **luôn** bật.
+6. `themes_verified` / `languages_verified` chỉ ghi thứ **thực sự đã kiểm**. Đây là chỗ hay
+   bị ghi khống nhất (`guardrail.md` G10).
+7. Agent nhận envelope phải kiểm envelope trước khi làm việc. Thiếu trường hoặc mâu thuẫn
+   (ví dụ `confidence: low` mà `next_agent: fix-implementer`) → trả về ngay, không xử lý.
+8. `category: security` thắng mọi nhóm khác. Một lỗi vừa lệch layout vừa lộ credential thì
+   `next_agent: security-defect-fixer`; phần UI tách thành `defect_id` riêng, xử lý sau.
+9. `blocked_on` của role 7 có thể chứa câu hỏi **chính sách** (`needs-security-decision`).
+   Đó là chờ hợp lệ — người trả lời là Cowork Team, không phải agent khác.

agent/workflow/intake_to_fix.md

@@ -0,0 +1,97 @@
+# Workflow — từ phản ánh của người dùng tới PR
+
+## 1. Pipeline
+
+```text
+  Người dùng báo lỗi (chat / issue / miệng)
+              │
+              ▼
+  ┌───────────────────────────┐
+  │ 1. ui-bug-triage          │  → defect_record.md
+  │    Planner                │     + category + severity + confidence
+  └───────────┬───────────────┘
+              │ route theo category  (security THẮNG mọi nhóm khác)
+      ┌───────┬─┴──────┬──────────┬───────────┐
+      ▼       ▼        ▼          ▼           ▼
+  ┌────────┐┌────────┐┌──────────┐┌─────────┐ not-ui
+  │ 2.     ││ 3.     ││ 4.       ││ 7.      │ → RETURN_TO_REPORTER
+  │ visual ││ flow   ││ i18n-a11y││ security│   (mở issue type:bug thường)
+  └────┬───┘└───┬────┘└────┬─────┘└────┬────┘
+       └────────┼──────────┴───────────┘
+                │   ⚠ role 7 có thể dừng ở đây:
+                │   4 câu chính sách chưa có đáp án
+                │   → RETURN_TO_REPORTER (needs-security-decision)
+                ▼  fix_plan.md
+  ┌───────────────────────────┐
+  │ 5. fix-implementer        │  → patch + fix_report.md
+  │    Executor (SỬA FILE)    │     + CASAN gate output
+  └───────────┬───────────────┘
+              ▼
+  ┌───────────────────────────┐
+  │ 6. regression-reviewer    │  → verdict + pr_body.md
+  │    Reviewer               │
+  └───────────┬───────────────┘
+       FAIL ──┘ (quay lại 5, hoặc về 2/3/4 nếu sai nguyên nhân gốc)
+       PASS ──▶ Cowork Team review → merge
+```
+
+## 2. Ai được làm gì
+
+| Agent | Đọc | Sửa file | Chạy lệnh | Quyết định |
+|---|---|---|---|---|
+| 1. triage | ✅ | ❌ | ✅ (grep, tra manifest) | phân loại + route |
+| 2/3/4. specialist | ✅ | ❌ | ✅ (đọc, kiểm LOC) | nguyên nhân gốc + phương án |
+| 7. security | ✅ | ❌ | ✅ (đọc, `git log -S`) | lỗ hổng + migration; **không** quyết chính sách |
+| 5. implementer | ✅ | ✅ | ✅ (git, pytest, gate) | cách hiện thực trong phạm vi plan |
+| 6. reviewer | ✅ | ❌ | ✅ (git, pytest, gate) | PASS / FAIL |
+| Cowork Team | — | — | — | **merge** |
+
+Chỉ **một** agent được sửa file. Ranh giới này là thứ giữ cho pipeline review được.
+
+## 3. Cổng chuyển bước
+
+Không bước nào được đi tiếp nếu chưa đạt:
+
+| Từ → Đến | Điều kiện |
+|---|---|
+| 1 → 2/3/4 | `confidence >= medium`, có ít nhất một `file:line`, đã redact |
+| 2/3/4 → 5 | Đúng **một** nguyên nhân gốc, có cách kiểm chứng, không vượt 400 LOC (hoặc đã có kế hoạch tách) |
+| 7 → 5 | Như trên, **cộng thêm**: có đường di trú cho cả 4 nhóm người dùng, và 4 câu chính sách đã có đáp án của Cowork Team |
+| 5 → 6 | 5 cổng CASAN xanh, test regression đỏ-trước-xanh-sau |
+| 6 → người | Verdict PASS/PASS_WITH_NOTES + `pr_body` |
+
+`confidence: low` ở bất kỳ đâu → quay về bước 1. Không đoán tiếp.
+
+## 4. Vòng lặp và giới hạn
+
+- FAIL ở bước 6 → về bước 5 (lỗi hiện thực) hoặc về 2/3/4 (sai nguyên nhân gốc).
+- Quá **2 vòng** mà vẫn FAIL → dừng, đưa người thật vào. Vòng thứ ba thường có nghĩa là
+  `defect_record` sai từ đầu, không phải bản vá sai.
+
+## 5. Đường tắt hợp lệ
+
+| Tình huống | Đường tắt |
+|---|---|
+| Lỗi chính tả một chuỗi, đã biết chính xác key | 1 → 4 → 5 → 6, bỏ giai đoạn điều tra ở bước 4 |
+| Thiếu key i18n, UI hiện ra `a.b_c` | 1 → 4 → 5 → 6 |
+| Lỗi do chính bản vá vừa merge | về thẳng 5 nếu nguyên nhân gốc chưa đổi |
+| Dev báo thẳng một lỗ hổng, không qua triệu chứng giao diện | vào thẳng 7, bỏ bước 1 |
+
+Không có đường tắt nào bỏ qua bước **6**.
+
+## 6. Chạy bằng Claude Code
+
+```bash
+mkdir -p .claude/agents && cp agent/roles/*.md .claude/agents/
+```
+
+Rồi lần lượt:
+
+```text
+> dùng ui-bug-triage cho phản ánh này: "màn Folder kéo to ra thì mất cây thư mục bên trái"
+> dùng ui-visual-fixer với defect_record ở trên
+> dùng fix-implementer với fix_plan ở trên
+> dùng regression-reviewer với patch vừa rồi
+```
+
+Chạy tuần tự, không song song — mỗi bước phụ thuộc output của bước trước.