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); (7) mọi REQ ⏳/🔵 có lý do + ngày (PRD-001 §7); (8) mọi màn hình đang chạy thuộc về một persona + một REQ (PRD-001 §8). 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 (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 | 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 prodQuan hệ với Audit Standard
QG chặn một thay đổi trước khi vào production. Audit Standard (AS-01..AS-10) đ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.
Trace
- REQ-DOC-02/03 → QG-001/002; REQ-DOC-05 → audit-standard.
- Cột QG trong PRD-001 §5 chỉ định gate cho từng REQ; traceability.md tổng hợp.