cowork-local/agent/knowledge/quality_gates.md

CASAN Quality Gate — cổng bắt buộc trước PR

Nguồn: README.md, scripts/run_quality_gate.py.

---

1. Năm cổng

Cổng	Script	Kiểm tra
C — Clean Architecture	scripts/check_imports.py	domain/ và application/ không import PySide6, PySide2, PyQt6, PyQt5, ui, app
A — Atomic & Secrets	scripts/audit_security.py	Secret/plaintext trong file .py và file config
S — Single Responsibility	scripts/check_loc.py --max-lines 400	Mọi module production <= 400 LOC
O — Orphan Module	scripts/check_orphan_modules.py	Module không được import từ đâu
A/N — Tests	pytest	Toàn bộ suite

2. Lệnh

# Đủ 5 cổng — chạy trước khi tạo PR
python scripts/run_quality_gate.py

# Chỉ guard tĩnh, bỏ test — vòng lặp sửa nhanh
python scripts/run_quality_gate.py --skip-tests

# Từng cổng
python scripts/check_imports.py
python scripts/audit_security.py
python scripts/check_loc.py --max-lines 400
pytest tests/e2e/test_smoke.py -v

3. Chạy test UI headless

QT_QPA_PLATFORM=offscreen pytest tests/ui -q          # bash
$env:QT_QPA_PLATFORM="offscreen"; pytest tests/ui -q  # PowerShell

64/108 module test dựng widget thật và 20 module import PySide6 ở module scope, nên môi trường test phải có đủ runtime dependency. Chỉ có một requirements.txt, không có cặp runtime/test riêng.

4. Bẫy khi sửa bug UI

• Gate S rất dễ vỡ khi vá bug. Nhiều file UI đã sát 400 dòng. Trước khi thêm code:

  python scripts/check_loc.py --max-lines 400 | grep <tên file>
  

  Sắp vượt → tách module và nêu trong fix_plan.md trước khi làm (guardrail.md G6).

• Gate O bắt module mồ côi. Tách file mới ra mà chưa import vào đâu là Gate O đỏ. Tách và nối dây trong cùng một commit.

• Gate C ít khi liên quan bug UI — trừ khi bản vá "tiện tay" import widget vào application/. Đó là dấu hiệu sửa sai tầng.

• File .py mới phải được git add ngay. tests/test_no_ignored_source.py::test_khong_file_py_nao_bi_bo_quen_chua_theo_doi quét git ls-files --others --exclude-standard và làm suite đỏ nếu có file .py chưa theo dõi trong thư mục nguồn. File test mới cũng tính. Triệu chứng giống hệt regression, nhưng không phải:

  AssertionError: File mã nguồn chưa được git add — clone sạch sẽ thiếu:
      tests/ui/test_<...>.py
  

• .venv không được nằm trong repo. install.bat dựng venv ở %LOCALAPPDATA%\CoworkLocal chính vì gate đi bộ toàn cây thư mục — một .venv trong repo biến mọi module vendored thành vi phạm Gate O.

5. Định nghĩa "xong"

Từ docs/governance/definition-of-done.md:

• code xong;
• test liên quan pass;
• tài liệu cập nhật nếu cần;
• PR đã được review;
• đã merge vào nhánh mặc định.

Một PR = một thay đổi logic. Không gộp nhiều bug UI không liên quan vào một PR.

Đóng góp từ FSG AI Core Team chỉ "xong" khi PR đã merge vào Cowork Local — "Core AI code xong" hoặc "pre-review pass" không phải Done. Bằng chứng bắt buộc: core issue reference, PR, evidence test, reviewer phía Cowork, merge commit.

---

6. Suite này vốn đã KHÔNG xanh

Tại e5fa21e (2026-09-07), chạy đầy đủ trên Windows + Python 3.14 cho ra:

11 failed, 884 passed, 2 skipped, 66 errors

Nghĩa là "pytest đỏ" không nói lên điều gì về bản vá của bạn. Bắt buộc phải so với baseline, và so bằng danh sách tên test:

git stash push --include-untracked -m baseline
QT_QPA_PLATFORM=offscreen pytest -q > /tmp/base.txt 2>&1
git stash pop
QT_QPA_PLATFORM=offscreen pytest -q > /tmp/after.txt 2>&1

grep "^FAILED" /tmp/base.txt  | sed 's/ - .*//' | sort > /tmp/f_base.txt
grep "^FAILED" /tmp/after.txt | sed 's/ - .*//' | sort > /tmp/f_after.txt
comm -13 /tmp/f_base.txt /tmp/f_after.txt      # rỗng = không regression

Không so con số tổng: một test cũ hỏng cộng một test mới xanh cho ra cùng con số.

Nhóm đỏ lớn nhất hiện nay là tests/characterization/test_co4e_runs_page.py — RuntimeError: libshiboken: Internal C++ object (QGraphicsScene) already deleted (bẫy P13 trong qt_pitfalls.md). Chưa ai nhận sửa.

Gate A và Gate S cũng đỏ sẵn:

• A — 3 phát hiện trong tests/test_project_context_{e2e,issue,knowledge}.py;
• S — core/chat_agent.py 423 LOC, mcp_servers/project_context/providers/knowledge.py 408 LOC.

Đừng nhận nhầm bốn thứ trên là do bản vá của mình (guardrail.md G10).