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