ai-developer-skill-os 9.1.1 → 9.3.0

package/.agents/skills/qk-engineering-standard/SKILL.md

@@ -1,8 +1,8 @@
 ---
 # ── Identity ───────────────────────────────────────────────
 name: qk-engineering-standard
-version: 9.1.0
-status: stable
+version: 9.2.1
+status: relocated
 description: "Ép buộc SOLID, DRY, Clean Code với ngưỡng số liệu cụ thể — không có rule mơ hồ."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
@@ -83,511 +83,7 @@ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 ---
 
 # qk-engineering-standard — Code Quality Enforcer
-
-> **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 / Architecture (vd: ngưỡng định lượng độ phức tạp cyclomatic, DRY, SOLID).
-
-- 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:* Convention hoặc ranh giới kỹ thuật mới (vd: áp đặt giới hạn 100 dòng cho file AGENTS.md).
-
-- 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:* Cảnh báo linter 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 / Architecture (vd: ngưỡng định lượng độ phức tạp cyclomatic, DRY, SOLID).
-
-- 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:* Convention hoặc ranh giới kỹ thuật mới (vd: áp đặt giới hạn 100 dòng cho file AGENTS.md).
-
-- 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:* Cảnh báo linter 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:* Convention hoặc ranh giới kỹ thuật mới (vd: áp đặt giới hạn 100 dòng cho file AGENTS.md).
-
-- 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:* Cảnh báo linter 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:* Convention hoặc ranh giới kỹ thuật mới (vd: áp đặt giới hạn 100 dòng cho file AGENTS.md).
-
-- 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:* Cảnh báo linter 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
-- [ ] Target file(s) or module(s) are specified
-
-```
-On missing precondition:
-  EXIT: BLOCKED
-  Message: "Vui lòng chỉ định file hoặc module cần kiểm tra."
-```
-
-## Scope
-- ✅ Detect violations with exact file:line references
-- ✅ Classify by severity with concrete thresholds
-- ✅ Suggest minimal, targeted refactors
-
-## Non-Goals
-- ❌ Auto-fix code — report only (fixes go to qk-bug-resolution or qk-feature-delivery)
-- ❌ Rewrite architecture
-- ❌ Touch files outside the specified scope
-
-## Concrete Thresholds (Non-Negotiable)
-**Các giới hạn dưới đây được dùng để định lượng vi phạm rác mã (R-C-09) và bảo mật (R-SEC-04):**
-
-```yaml
-function:
-  max_lines: 30              # Lines of code, excluding comments/blanks
-  max_cyclomatic_complexity: 10
-  max_parameters: 4
-
-file:
-  max_lines: 300
-  max_public_methods_per_class: 10  # God Class threshold
-
-dry:
-  violation_threshold: 3    # Same logic duplicated in ≥ 3 places
-
-separation_of_concerns:
-  violation: "File mixes UI rendering + API calls + State management"
-
-naming:
-  min_variable_name_length: 2  # Single-letter vars (except i,j,k in loops)
-  max_abbreviation_ratio: 0.3  # > 30% abbreviations in identifiers = violation
-
-dependency:
-  max_imports_per_file: 15  # Beyond this: likely a God File
-```
-
-## Priority Order
-
-| Priority | Check | Severity | Skip Threshold |
-|----------|-------|----------|----------------|
-| P1 | Security violations (hardcoded secrets, SQL injection) | CRITICAL | Never |
-| P2 | God Functions > 30 lines / complexity > 10 | HIGH | Budget < 30% |
-| P3 | God Files > 300 lines / God Classes | HIGH | Budget < 40% |
-| P4 | DRY violations (3+ duplicates) | MEDIUM | Budget < 50% |
-| P5 | Mixed concerns in single file | MEDIUM | Budget < 60% |
-| P6 | Naming convention violations | LOW | Budget < 70% |
-| P7 | Excessive imports / coupling | LOW | Budget < 80% |
-
-## Workflow
-
-### Phase 1 — Scan for Critical & High Violations
-
-**Steps:**
-1. `grep_search` — search for: hardcoded secrets, `console.log`, `eval(`, `any` types
-2. `view_file[targeted]` — read function definitions to count lines and parameters
-3. Log each violation with Evidence Format
-
-**Decision:**
-```
-IF CRITICAL violation found (e.g., hardcoded API key)
-  → Report immediately, mark EXIT: FAILED
-  → Still continue scanning (don't stop at first critical)
-
-IF function line count > 30 OR complexity > 10
-  → Log as [HIGH]
-
-IF file line count > 300
-  → Log as [HIGH] — God File suspected
-```
-
-**Exit When:**
-- All P1+P2+P3 checks done → go to Phase 2
-- Token budget < 30% → go to Phase 3 directly with PARTIAL flag
-
-### Phase 2 — Scan for Medium & Low Violations
-
-**Steps:**
-1. `grep_search` — find duplicate logic patterns (copy-paste code)
-2. Check import counts per file
-3. Check naming conventions
-
-**Decision:**
-```
-IF same logic block appears ≥ 3 times
-  → Log as [MEDIUM] DRY violation
-
-IF file has > 15 imports
-  → Log as [LOW] — potential God File or tight coupling
-
-IF token budget < 50%
-  → Skip P6+P7, go to Phase 3
-```
-
-### Phase 3 — Score & Report
-
-**Steps:**
-1. Count violations by severity
-2. Calculate health score: start at 100, deduct per violation
-3. Generate report
-
-**Deduction Scale:**
-```
-CRITICAL: -25 pts each
-HIGH:     -10 pts each
-MEDIUM:   -5 pts each
-LOW:      -2 pts each
-```
-
-**Decision:**
-```
-IF score ≥ 80 AND no CRITICAL violations
-  → EXIT: SUCCESS
-
-IF score 60–79 OR any HIGH violations
-  → EXIT: PARTIAL — list fixes needed
-
-IF score < 60 OR any CRITICAL violations
-  → EXIT: FAILED — requires immediate action
-```
-
-## Confidence Model
-
-| Level | Condition | Action |
-|-------|-----------|--------|
-| HIGH | Direct line count, exact pattern match | Report as violation |
-| MEDIUM | Inferred cyclomatic complexity without tool | Note estimate |
-| LOW | Architectural smell inferred from structure | Mark as "suspected — verify manually" |
-
-## Severity
-
-| Level | Definition | Example |
-|-------|-----------|---------|
-| CRITICAL | Security risk or data integrity | Hardcoded secret, SQL injection via string concat |
-| HIGH | Technical debt that blocks scaling | Function 80 lines, God Class 15+ methods |
-| MEDIUM | DRY or SoC violation, fixable in < 1 hour | Same validation logic in 3 components |
-| LOW | Style/naming issue, non-blocking | Single-letter variable `x` outside loop |
-
-## Evidence Format
-
-```
-[SEVERITY] path/to/file.ts:LINE
-Rule:       [FUNCTION_LENGTH | COMPLEXITY | DRY | SOC | NAMING | GOD_CLASS | SECRET]
-Reason:     [specific measurement vs threshold]
-Confidence: [HIGH|MEDIUM|LOW]
-Fix:        [one-line suggestion]
-Deduction:  -N pts
-```
-
-**Example:**
-```
-[HIGH] src/services/order.service.ts:45
-Rule:       FUNCTION_LENGTH
-Reason:     Function `processOrder` is 87 lines (threshold: 30)
-Confidence: HIGH
-Fix:        Extract payment logic to `processPayment()`, shipping to `scheduleShipment()`
-Deduction:  -10 pts
-```
-
-## Retry Policy
-```
-Audit is read-only — no retry needed.
-If file is inaccessible → skip and note in report as PARTIAL.
-```
-
-## Escalation Rules
-
-```
-BLOCKED: No target specified
-Missing:
-  - File path or module name to audit
-Questions:
-  1. Bạn muốn kiểm tra file nào hoặc toàn bộ module nào?
-  2. Có ngưỡng cụ thể nào bạn muốn thay đổi không? (mặc định: 30 lines/function)
-```
-
-## Handoff Contract
-
-### Consumes
-```json
-{
-  "from": "user or qk-orchestrator",
-  "required_fields": ["target_files_or_module"],
-  "optional_fields": ["custom_thresholds"]
-}
-```
-
-### Produces
-```json
-{
-  "to": "user",
-  "output_fields": ["health_score", "violations_list", "severity_counts", "exit_code"]
-}
-```
-
-## Output Format
-
-```
-⚙️ Engineering Standard Audit
-─────────────────────────────────────────────────
-Target:      [file or module]
-
-Health Score: [X/100]
-  CRITICAL violations: [N] (-Npts)
-  HIGH violations:     [N] (-Npts)
-  MEDIUM violations:   [N] (-Npts)
-  LOW violations:      [N] (-Npts)
-
-Violations (priority order):
-  [SEVERITY] file:LINE — Rule — reason — Fix — (-Xpts)
-
-Required Actions:
-  1. [Most critical fix]
-  2. [Second fix]
-
-Exit Code:   [SUCCESS | PARTIAL | FAILED]
-```
-
-## Exit Codes
-
-| Code | Meaning | When |
-|------|---------|------|
-| SUCCESS | Score ≥ 80, no CRITICAL | Code meets V7.5 standards |
-| PARTIAL | Score 60–79 or incomplete scan | Some categories skipped |
-| BLOCKED | No target specified | Cannot audit without scope |
-| FAILED | Score < 60 or CRITICAL found | Immediate action required |
-
-## References
-- Detailed thresholds with rationale: `references/thresholds.md`
-- Anti-Patterns Blacklist: `references/anti-patterns.md`
-
----
+> **⚠️ ARCHIVED (v9.2.1):** Downgraded thành rule. Nội dung đã được merge vào `.agents/rules/coding.md` (R-C-10). Không cần gọi trực tiếp — áp dụng tự động trong mọi skill có `side_effects: edit_files`.
 
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.