ai-developer-skill-os 9.1.2 → 9.3.0

package/.agents/skills/qk-web-quality-gate/SKILL.md

@@ -1,9 +1,9 @@
----
+---
 # ── Identity ───────────────────────────────────────────────
 name: qk-web-quality-gate
-version: 9.1.0
+version: 9.2.0
 status: experimental
-description: "Kiểm toán tổng thể chất lượng Web: Accessibility (A11y), SEO, Web Performance, Security, UX Heuristics."
+description: "Đo lường chất lượng kỹ thuật Web: Accessibility violations (WCAG), Core Web Vitals, Lighthouse score, SEO tags, security headers. Output là số đo và lỗi kỹ thuật cụ thể. Dùng skill này khi user nhắc đến: a11y, accessibility, wcag, lighthouse, core web vitals, seo audit, page speed, performance score, security headers — KHÔNG dùng cho review thiết kế UI hay spacing."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
 # ── V9: Classification ─────────────────────────────────────
@@ -24,12 +24,17 @@ complexity:
     has_external_dependency: true
     has_breaking_change: false
 
-triggers:
-  - "kiểm tra web"
-  - "tối ưu web"
-  - "lighthouse"
-  - "audit ui"
-  - "core web vitals"
+triggers:
+  - "a11y"
+  - "accessibility"
+  - "wcag"
+  - "lighthouse"
+  - "core web vitals"
+  - "seo audit"
+  - "page speed"
+  - "performance score"
+  - "security headers"
+
 
 # ── V8: References ─────────────────────────────────────────
 workflow: feature-delivery
@@ -43,7 +48,8 @@ tools:
   - terminal
 
 related_skills:
-  - qk-frontend-architecture
+  - qk-ui-audit
+  - qk-ui-builder
 
 knowledge_scope:
   domain:
@@ -85,7 +91,7 @@ latency: slow
 risk: low
 side_effects: read_only
 produces: [report]
-consumes: [user-description]
+consumes: [user-description, source-code]
 
 token_budget:
   max_files_read: 5
@@ -93,483 +99,99 @@ token_budget:
   max_shell_commands: 2
   stop_early: true
 
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 ---
 
-# qk-web-quality-gate — Web Quality Auditor
+# qk-web-quality-gate — Web Quality, A11y & Performance Auditor
 
 > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
 
-## Memory Workflow
-
-### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
-- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
-  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
-  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
-
----
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-  - 👉 *Domain Focus:* Convention / Hard Bug (vd: chỉ số Core Web Vitals LCP/CLS, rủi ro bot SEO/A11y).
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Mẫu tối ưu hiệu năng web (vd: chiến lược lazyload hình ảnh, bundle partition).
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .ai-local/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Report Lighthouse của lần đo test tạm thời.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
-
-
-
-### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
-- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
-  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
-  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
-
----
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-  - 👉 *Domain Focus:* Convention / Hard Bug (vd: chỉ số Core Web Vitals LCP/CLS, rủi ro bot SEO/A11y).
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Mẫu tối ưu hiệu năng web (vd: chiến lược lazyload hình ảnh, bundle partition).
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .ai-local/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Report Lighthouse của lần đo test tạm thời.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
-
-
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.agents/knowledge/index.yaml` (Shared Project Knowledge)
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-  - 👉 *Domain Focus:* Convention / Hard Bug (vd: chỉ số Core Web Vitals LCP/CLS, rủi ro bot SEO/A11y).
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Mẫu tối ưu hiệu năng web (vd: chiến lược lazyload hình ảnh, bundle partition).
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Report Lighthouse của lần đo test tạm thời.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Mẫu tối ưu hiệu năng web (vd: chiến lược lazyload hình ảnh, bundle partition).
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Report Lighthouse của lần đo test tạm thời.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Mẫu tối ưu hiệu năng web (vd: chiến lược lazyload hình ảnh, bundle partition).
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Report Lighthouse của lần đo test tạm thời.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
----
----
-
-## Preconditions
-- [ ] Ứng dụng web đã có thể chạy hoặc code đã được viết một phần.
+Chịu trách nhiệm đo lường và đánh giá các chỉ số chất lượng kỹ thuật của ứng dụng Web: **Accessibility (WCAG 2.1 AA) → Core Web Vitals (LCP, FID/INP, CLS) → SEO meta tags → Security Headers**. Xuất báo cáo định lượng và chỉ dẫn khắc phục cụ thể.
 
-## Scope
-- Thực hiện kiểm toán A11y (Accessibility standards như WCAG).
-- Đánh giá Performance (Core Web Vitals, Bundle size, Lazy loading, Cache, Optimize images).
-- Kiểm tra SEO best practices (Meta tags, heading structure, semantic HTML).
-- Đánh giá UX Heuristics cơ bản.
-- Đưa ra khuyến nghị (Recommendation), không phải tự tay fix code nếu chưa được yêu cầu.
-
-## Non-Goals
-- ❌ Provide implementation outside of Web Performance & Accessibility scope
-- ❌ Override explicit user directives without explanation
-- ❌ Guess ambiguous requirements without asking
-
-## Priority Order
-
-| Priority | Task | Skip Threshold |
-|----------|------|----------------|
-| P1 | Core Web Performance & Accessibility analysis and decision making | Never |
-| P2 | Validation of existing patterns | Budget < 30% |
-| P3 | Detailed documentation generation | Budget < 50% |
-| P4 | Edge case exploration | Budget < 70% |
-
-## Workflow
-
-### Phase 1 — Context Loading
-**Steps:**
-1. Read existing configuration and requirements related to Web Performance & Accessibility.
-2. Check for missing preconditions.
-
-**Decision:**
-```
-IF context is clear
-  → Confidence: HIGH → go to Phase 2
-ELSE
-  → EXIT: BLOCKED — ask user
-```
+---
 
-### Phase 2 — Analysis & Strategy
-**Steps:**
-1. Analyze the current state against Web Performance & Accessibility best practices.
-2. Formulate strategy or audit report based on findings.
+## Preconditions
 
-**Decision:**
-```
-IF strategy/audit is complete
-  → Confidence: HIGH → go to Phase 3
-ELSE IF minor gaps exist
-  → Confidence: MEDIUM → proceed with assumptions noted
-```
+Trước khi audit chất lượng web, AI BẮT BUỘC kiểm tra:
 
-### Phase 3 — Finalization
-**Steps:**
-1. Generate final report or configuration.
-2. Prepare handoff data for subsequent skills.
+- [ ] Xác định trang hoặc component web cần kiểm tra.
+- [ ] Xác định frontend framework và rendering method (SSR, SSG, CSR, Next.js, Nuxt) từ `.agents/DEV_PROFILE.md`.
+- [ ] Đảm bảo có thể truy cập mã nguồn template HTML / JSX để đọc semantic tags.
+- [ ] Nếu trang hoàn toàn là client-side SPA mà không có mã nguồn cấu trúc DOM:
+  → **EXIT: BLOCKED**
+  → Báo cáo user cung cấp URL môi trường staging hoặc file mã nguồn template tương ứng.
 
-## Confidence Model
+---
 
-| Level | Condition | Action |
-|-------|-----------|--------|
-| HIGH | All preconditions met, context fully understood | Proceed directly |
-| MEDIUM | Some context missing but safe defaults exist | Proceed and note assumptions |
-| LOW | Core requirements missing | EXIT: BLOCKED |
+## Scope
 
-## Severity (for findings)
+✅ Skill này làm:
+- Kiểm toán Accessibility (A11y theo chuẩn WCAG 2.1 AA):
+  - Semantic HTML (`<main>`, `<nav>`, `<header>`, `<h1>-<h6>` thứ tự đúng).
+  - ARIA attributes (`aria-label`, `aria-expanded`, `aria-hidden`, `role`).
+  - Keyboard navigation (tab order, focus trap trong modals, skip links).
+  - Alt text cho hình ảnh và caption cho media.
+- Phân tích Core Web Vitals & Performance:
+  - LCP (Largest Contentful Paint): Tối ưu hóa ảnh (next/image, webp, priority loading).
+  - CLS (Cumulative Layout Shift): Khai báo width/height cho hình ảnh, placeholder cho ad slots.
+  - INP/FID: Tối ưu bundle size, dynamic imports / code-splitting.
+- Kiểm tra SEO Technical: Title tag, Meta description, OpenGraph tags, Canonical link, Robots/Sitemap.
+- Kiểm tra HTTP Security Headers khuyến nghị: CSP, X-Frame-Options, HSTS.
+
+❌ Skill này KHÔNG làm:
+- Đánh giá tính thẩm mỹ hoặc spacing thị giác (→ `qk-ui-audit`).
+- Tự viết component UI mới từ đầu (→ `qk-ui-builder`).
+- Thiết lập hạ tầng CDN hoặc server proxy Nginx/Cloudflare (→ `qk-devops-platform`).
 
-| Level | Definition |
-|-------|-----------|
-| CRITICAL | Severe violation of Web Performance & Accessibility principles |
-| HIGH | Significant risk or technical debt |
-| MEDIUM | Suboptimal pattern but functional |
-| LOW | Minor style or documentation issue |
+---
 
-## Evidence Format
+## Execution Steps
 
+### Step 1 — Semantic & A11y DOM Inspection
 ```
-[SEVERITY] Context/File
-Issue:      [what was found]
-Confidence: HIGH
-Recommendation: [actionable advice]
+Inputs:  Page/Component source code
+Actions:
+  - Kiểm tra tính hợp lệ của cây phân cấp headings (h1 -> h2 -> h3, không nhảy cóc).
+  - Soát tất cả thẻ `<img>` thiếu `alt` hoặc thẻ tương tác (`<button>`, `<a>`) thiếu text/aria-label.
+  - Kiểm tra form inputs có gắn kèm `<label>` tường minh hay không.
+Output: A11y violation list
 ```
 
-## Retry Policy
+### Step 2 — Performance & Core Web Vitals Analysis
 ```
-Task fails due to missing context
-  └─ Ask user for clarification
-       ├─ Provided → Retry Phase 1
-       └─ Not provided → EXIT: BLOCKED
+Inputs:  Asset imports, Rendering architecture
+Actions:
+  - Kiểm tra cách load font chữ (font-display: swap) và CSS render-blocking.
+  - Phát hiện các ảnh dung lượng lớn chưa được responsive srcset hoặc nén modern formats (AVIF/WebP).
+  - Đánh giá chiến lược lazy-loading cho các components nằm dưới màn hình đầu tiên (below the fold).
+Output: Web Vitals bottleneck map
 ```
 
-## Escalation Rules
-
+### Step 3 — SEO & Security Header Audit
 ```
-BLOCKED: Missing critical context for Web Performance & Accessibility
-Missing:
-  - [Specific requirement]
-Questions:
-  1. Bạn có thể cung cấp thêm thông tin về yêu cầu này không?
-  2. Mục tiêu chính của bạn là gì?
-Recommended Assumptions: none
+Inputs:  HTML Head configuration, Next.js metadata / Nuxt useHead
+Actions:
+  - Soát độ dài Title (50-60 ký tự) và Description (150-160 ký tự).
+  - Kiểm tra cấu hình thẻ mạng xã hội (og:image, og:title, twitter:card).
+  - Đánh giá Content Security Policy (CSP).
+Output: SEO & Security posture report
 ```
 
-## Handoff Contract
-
-### Consumes
-```json
-{
-  "from": "user or qk-orchestrator",
-  "required_fields": ["context"],
-  "optional_fields": ["existing_config"]
-}
+### Step 4 — Remediation Guide Formulation
 ```
-
-### Produces
-```json
-{
-  "to": "user or downstream skill",
-  "output_fields": ["strategy_report", "exit_code"]
-}
+Inputs:  Findings across all categories
+Actions:
+  - Tổng hợp thành bảng điểm định lượng và phân loại độ ưu tiên (P0: Blockers, P1: High, P2: Polish).
+  - Cung cấp đoạn code JSX/HTML sửa mẫu trực quan.
+Exit: SUCCESS
 ```
 
-## Exit Codes
+---
+
+## Prompt Template
 
-| Code | Meaning | When |
-|------|---------|------|
-| SUCCESS | Web Performance & Accessibility task completed successfully | Strategy/audit generated |
-| PARTIAL | Task completed with assumptions | Medium confidence |
-| BLOCKED | Missing context | Cannot proceed |
-| FAILED | Critical conflict or error | Unresolvable constraint |
+```
+Trang / URL:       [Đường dẫn file page hoặc route URL cần kiểm tra]
+Trọng tâm audit:   [A11y WCAG / Core Web Vitals / SEO Technical / Tất cả]
+Vấn đề ghi nhận:   [Chậm tải trang, lighthouse điểm đỏ, cảnh báo screen reader, ...]
+```

package/.agents/workflows/bug-resolution.yml

@@ -98,21 +98,21 @@ steps:
       condition: "file thuộc vùng auth/payment/permission/migration"
       message: "Patch này chạm vào code nhạy cảm. Xác nhận an toàn trước khi thay đổi."
   - id: verify
-    name: "Xác minh fix"
-    purpose: "Xác nhận bug đã được fix và không có regression"
+    name: "Xác minh fix + quality gate"
+    purpose: "Xác nhận bug đã được fix, không có regression, code đạt quality threshold"
     required: true
     skip_if: null
     inputs:
       - patched_files
     outputs:
       - verification_result   # PASS | FAIL | PARTIAL
-      - evidence_of_fix       # Re-read patched section
+      - evidence_of_fix
+      - quality_gate_result   # PASS | FAIL
     actions:
       - "Re-read patched code section"
       - "Chạy test liên quan nếu có"
-      - "Kiểm tra caller/dependent nếu interface thay đổi"
-      - "Đảm bảo tuân thủ R-SEC-04 (Security Boundary)"
-      - "Đảm bảo tuân thủ R-C-09 (Zero-Slop)"
+      - "Áp dụng shared quality gate → xem: .agents/workflows/shared/quality-gate.yml"
+      - "  Checklist: universal_checks + bug-resolution specific checks"
       - "Ghi log execution trace vào evals/traces/"
     exit_on_fail: FAILED