---
url: https://docs.nemo12.com/quality/quality-gates.md
description: >-
  Danh mục Quality Gates (QG): mỗi REQ active có ít nhất một cổng kiểm chứng,
  đánh dấu thủ công hay CI-enforced.
---

# Quality Gates (QG)

Mỗi REQ active phải có ít nhất một QG kiểm chứng. Giai đoạn hiện tại (docs + scaffold): các check đánh dấu 📋 chạy **thủ công khi review**; khi có CI đầy đủ chuyển sang 🤖 **CI-enforced**. Không production change nào (code, migration, content, rubric, prompt, algorithm) được publish mà không qua gate tương ứng (SDD-006 §15).

| ID | Tên | Kiểm gì | Cách kiểm | Trạng thái |
| --- | --- | --- | --- | --- |
| QG-001 | **Docs Integrity** | Frontmatter hợp lệ (id, status, sources, satisfies, verified_by); broken links; intake ledger đủ; trace closure 2 chiều (REQ↔SDD↔QG↔US — doc thiết kế hợp lệ gồm cả `reference/`); không có doc mồ côi; **trang sinh tự động không lệch source** (`npm run gen:reference` không tạo diff) | script `scripts/check-docs.mjs` + review | 📋 (script sẽ thêm) |
| QG-002 | **Requirements Quality** | (1) REQ **testable** — cấm từ mơ hồ "tốt / nhanh / dễ dùng / thân thiện / đẹp / tối ưu", thay bằng ngưỡng số, tên màn hình hoặc hành vi nhìn thấy được; (2) priority đúng một trong **M / S / C** — cấm "M?"; (3) có nguồn `SRC-xxx` hoặc người + ngày; (4) **không hai REQ mô tả cùng một hành vi** (gộp thì để 🗄️ superseded, không xóa ID); (5) mọi US đúng format + có **acceptance criteria quan sát được, mô tả kết quả người dùng thấy** (không mô tả giải pháp kỹ thuật), US đã chạy ghi kèm màn hình/endpoint thật; (6) mọi REQ MUST map tới ≥1 US hoặc WF ([PRD-001 §6](../product/prd-001-nemo12-platform.md)); (7) mọi REQ ⏳/🔵 có lý do + ngày ([PRD-001 §7](../product/prd-001-nemo12-platform.md)); (8) mọi màn hình đang chạy thuộc về một persona + một REQ ([PRD-001 §8](../product/prd-001-nemo12-platform.md)). Rubric nền: `requirements-assessment` kế thừa chuyenchon (8 clusters/40 criteria) | rubric review + đối chiếu §6/§7/§8 với route thật trong `apps/*/src` | 📋 |
| QG-003 | **API Contract** | OpenAPI sinh từ router (không viết tay); mọi route có zod schema; backward compatibility (không breaking trong /v1); error taxonomy đúng SDD-006 §11 | typecheck + contract diff CI | 📋→🤖 |
| QG-004 | **Data & Migrations** | Một sequence migration duy nhất; idempotent; không DML destructive trộn DDL; migration tương thích deploy trước code; cấm email làm khóa (RISK-001); timestamps chuẩn | review + `wrangler d1 migrations` dry-run CI | 📋→🤖 |
| QG-005 | **Learner Intelligence Correctness** | Thuật toán mastery/confidence/priority/**retention** (decay, evidence tiers, review window — SRC-065) có unit tests hành vi (cấm source-regex tests — RISK-015); model versioning ghi đủ; recommendation có reason + versions; stopping criteria hoạt động; mastery không tự decay theo thời gian (SDD-017 §1) | behavior tests + review | 📋→🤖 |
| QG-006 | **Content Quality** | Rubric CC-QAF gốc; quality profile đủ 8 chiều có evidence; multi-evaluator variance check; candidate-version lifecycle (không sửa production trực tiếp); learner-evidence feedback loop | Quality Engine (SDD-003) + human review | 📋 |
| QG-007 | **Design System Compliance** | Chỉ dùng tokens; không fork component; không CSS per-page; sàn 14px; WCAG AA contrast/focus/touch-target; theme chỉ đổi lớp accent | lint + visual review | 📋→🤖 |
| QG-008 | **Security & Privacy** | Backend authz mọi truy cập learner data (parent↔family; mentor = role-gated xem mọi learner — SRC-037, bắt buộc audit log); RBAC không so sánh email (RISK-013); không hardcode secret/domain/audience; audit log; child-data: minimization, consent parent-first, retention; media moderation trước public | security review checklist + tests | 📋 |
| QG-009 | **Reliability** | 5 câu hỏi production-ready (SDD-006 §16); idempotency consumer; DLQ cấu hình; graceful degradation có fallback; observability bật mọi worker; binding được CI verify tồn tại (RISK-026); availability tier khai báo | review + smoke tests | 📋 |
| QG-010 | **AI Governance** | 100% AI calls qua AI Gateway `nemo12` (cấm probe-fallback — RISK-022); prompt registry versioned; output quan trọng lưu model/prompt_version/input_ref/confidence; Context Builder là đường duy nhất AI chạm learner data; cost dashboard | code review + gateway logs | 📋 |
| QG-011 | **Real Exam Bank Integrity** | Đề thật có provenance đủ (trường/hệ thi, vòng, môn, năm học, **URL nguồn — không lưu file đề**, Q-069 ✅); bài chỉ published khi có statement + lời giải **qua AI multi-evaluator đạt ngưỡng** (AI-first — SRC-035; owner spot-check theo tỷ lệ + item bị learner report) + ≥1 node link + ≥1 dạng bài; lời giải tự biên soạn (không sao chép site ngoài — SDD-012 §1.6); crawl chỉ nguồn công khai, robots/ToS-aware, provenance (SDD-014); personal state không ghi thẳng vào Learner Model (chỉ qua evidence); đề authentic immutable sau publish | deterministic checks content plane + review checklist (Coral) | 📋 |
| QG-012 | **Content Standards** | Kho nội dung đạt mọi chỉ tiêu số trong [content-standards.md](content-standards.md) (CS-01..CS-11): 6/6/6 cho cây D1, 5 / 3-6 / 3-6 / 1-2 cho cây Pearl, 1 lab live/unit, 10 câu/LX, ≥16 câu/bài, ~35% kho để dành đo, 100% câu hình học có hình, ngưỡng publish AI ≥0.72 | `npm run check:docs` (`check-curriculum-pearl.mjs` + `check-labs*.mjs`) + coverage pages sinh tự động | 🤖 (curriculum/lab) + 📋 (item/exam) |
| QG-013 | **Trace Closure — chiều ngược** | Mạng truy vết phải đóng ở **cả hai chiều**, không chỉ chiều xuôi. (1) **SRC mồ côi**: mọi `SRC-xxx` đánh ✅ trong intake phải nằm trong `sources:` của ít nhất một doc (SRC-596); (2) **REQ mồ côi**: mọi REQ ✔ trong PRD-001 phải nằm trong `satisfies:` của ít nhất một doc thiết kế (SRC-603). Mỗi loại đo **hai mức nợ riêng** — *nợ khai báo* (mã có trong thân bài nhưng vắng ở frontmatter, máy truy vết không thấy) và *nợ nội dung* (mã không xuất hiện ở đâu, tức quyết định chỉ còn trong commit message). Trần **chỉ đi một chiều**: thêm một mã mồ côi là CI đỏ, dọn bớt thì hạ trần trong cùng commit, cấm nâng trần | `scripts/check-src-canonical.mjs` + `scripts/check-req-canonical.mjs`, cả hai trong `npm run check:docs` | 🤖 |
| QG-014 | ~~Content Production — máy sinh, không gõ tay~~ **ĐÃ GỠ 2026-09-03 (SRC-672)** | Cổng này từng cấm nội dung learner được tạo trực tiếp trong phiên Claude Code hay dán từ hội thoại (SRC-635). Chủ dự án gỡ bỏ: nó chặn cả những lúc chính chủ dự án là tác giả, và chi phí chờ workflow lớn hơn lợi ích của việc ép một nguồn duy nhất. Số hiệu QG-014 **giữ lại chứ không tái sử dụng** — tài liệu cũ còn trỏ tới nó, đổi số là làm gãy tham chiếu. Xưởng nội dung (SDD-027) vẫn chạy và vẫn là đường tốt nhất khi có workflow; nay là **khuyến nghị**, không phải cổng chặn | không còn kiểm | 🗄️ |
| QG-015 | **Đường hỏng phải ghi lý do** | Mọi nhánh bỏ qua một lượt gọi model, một bản chấm, hay một bản thảo (`continue`, `catch {}`, `?? null`) **bắt buộc ghi lý do** vào chỗ người đọc được — `gate_reasons`, cột `problems`, hoặc `console.error` có tên mốc. Cấm nuốt lỗi im lặng. Cùng lý do: model/khoá của nhà cung cấp ngoài **không được nằm trên đường mặc định** — hỏng một khoá không được làm đứng cả một tầng | đọc `gate_reasons` của lượt chạy gần nhất: không được có mã chung chung kiểu `KHONG_GOI_DUOC` mà thiếu thông điệp kèm theo | 📋 |

## Pipeline CI bắt buộc (khi code vào)

```text
typecheck → lint → unit/behavior tests → API contract check → migration dry-run
→ design-system lint → docs check (QG-001) → security checks → deploy staging → deploy prod
```

## Quan hệ với Audit Standard

QG chặn **một thay đổi** trước khi vào production. [Audit Standard (AS-01..AS-10)](audit-standard/index.md) đo **trạng thái toàn hệ** tại một thời điểm — 255 chỉ báo pass / không pass. Một hệ có thể qua mọi QG mà vẫn điểm AS thấp, vì QG chỉ chặn cái mới, không đo cái đã tích tụ. Ánh xạ AS ↔ QG ở [audit-standard §14](audit-standard/release-and-reporting.md#_14-anh-xa-as-va-qg).

## Trace

* REQ-DOC-02/03 → QG-001/002; REQ-DOC-05 → [audit-standard](audit-standard/index.md).
* Cột QG trong [PRD-001 §5](../product/prd-001-nemo12-platform.md) chỉ định gate cho từng REQ; [traceability.md](../traceability.md) tổng hợp.