ai-developer-skill-os 9.1.2 → 9.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/.agents/AGENTS.md +139 -42
  2. package/.agents/DEV_PROFILE.md +95 -0
  3. package/.agents/registry/capability-graph.yml +171 -334
  4. package/.agents/registry/graph.json +37 -19
  5. package/.agents/registry/index.yaml +59 -13
  6. package/.agents/registry/skills-index.yml +204 -447
  7. package/.agents/rules/coding.md +23 -0
  8. package/.agents/rules/global.md +44 -30
  9. package/.agents/skills/_template/SKILL.md +2 -377
  10. package/.agents/skills/qk-access-policy/SKILL.md +98 -473
  11. package/.agents/skills/qk-agent-observability/SKILL.md +3 -439
  12. package/.agents/skills/qk-ai-builder/SKILL.md +132 -565
  13. package/.agents/skills/qk-api-consumer/SKILL.md +256 -0
  14. package/.agents/skills/qk-api-consumer/capability.yaml +21 -0
  15. package/.agents/skills/qk-api-consumer/evals/scorecard.yaml +29 -0
  16. package/.agents/skills/qk-api-lifecycle/SKILL.md +133 -456
  17. package/.agents/skills/qk-bug-resolution/SKILL.md +128 -561
  18. package/.agents/skills/qk-code-review/SKILL.md +142 -420
  19. package/.agents/skills/qk-context-loader/SKILL.md +99 -471
  20. package/.agents/skills/qk-data-engineer/SKILL.md +119 -340
  21. package/.agents/skills/qk-data-lifecycle/SKILL.md +89 -488
  22. package/.agents/skills/qk-db-optimizer/SKILL.md +102 -488
  23. package/.agents/skills/qk-design-system-engineering/SKILL.md +76 -461
  24. package/.agents/skills/qk-devops-platform/SKILL.md +77 -463
  25. package/.agents/skills/qk-docs/SKILL.md +88 -494
  26. package/.agents/skills/qk-engineering-standard/SKILL.md +4 -588
  27. package/.agents/skills/qk-fe-api-integration/SKILL.md +343 -343
  28. package/.agents/skills/qk-fe-api-integration/evals/scorecard.yaml +29 -29
  29. package/.agents/skills/qk-feature-delivery/SKILL.md +137 -445
  30. package/.agents/skills/qk-feature-delivery/evals/scorecard.yaml +1 -1
  31. package/.agents/skills/qk-frontend-architecture/SKILL.md +5 -479
  32. package/.agents/skills/qk-help/evals/scorecard.yaml +13 -13
  33. package/.agents/skills/qk-orchestrator/SKILL.md +63 -502
  34. package/.agents/skills/qk-orchestrator/references/routing-table.md +10 -14
  35. package/.agents/skills/qk-product-specification/SKILL.md +70 -479
  36. package/.agents/skills/qk-production-release/SKILL.md +80 -537
  37. package/.agents/skills/qk-project-audit/SKILL.md +174 -0
  38. package/.agents/skills/qk-project-bootstrap/SKILL.md +243 -471
  39. package/.agents/skills/qk-project-health/SKILL.md +97 -496
  40. package/.agents/skills/qk-project-memory/SKILL.md +76 -21
  41. package/.agents/skills/qk-refactor/SKILL.md +167 -384
  42. package/.agents/skills/qk-security-audit/SKILL.md +141 -463
  43. package/.agents/skills/qk-security-audit/capability.yaml +1 -2
  44. package/.agents/skills/qk-system-evolution/SKILL.md +343 -343
  45. package/.agents/skills/qk-system-evolution/evals/scorecard.yaml +26 -26
  46. package/.agents/skills/qk-test-engineering/SKILL.md +119 -509
  47. package/.agents/skills/qk-ui-audit/SKILL.md +73 -537
  48. package/.agents/skills/qk-ui-builder/SKILL.md +521 -482
  49. package/.agents/skills/qk-ui-system-builder/SKILL.md +68 -514
  50. package/.agents/skills/qk-upgrade/SKILL.md +301 -0
  51. package/.agents/skills/qk-upgrade/capability.yaml +24 -0
  52. package/.agents/skills/qk-upgrade/evals/scorecard.yaml +26 -0
  53. package/.agents/skills/qk-validation-gate/SKILL.md +4 -603
  54. package/.agents/skills/qk-web-quality-gate/SKILL.md +85 -463
  55. package/.agents/workflows/bug-resolution.yml +6 -6
  56. package/.agents/workflows/context-discovery.yml +94 -0
  57. package/.agents/workflows/feature-delivery.yml +8 -4
  58. package/.agents/workflows/refactor.yml +6 -3
  59. package/.agents/workflows/shared/quality-gate.yml +94 -0
  60. package/.agents/workflows/skin-governance.yml +115 -0
  61. package/README.md +152 -67
  62. package/package.json +2 -2
  63. package/tooling/build-registry.js +30 -8
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  # ── Identity ───────────────────────────────────────────────
3
3
  name: qk-engineering-standard
4
- version: 9.1.0
5
- status: stable
4
+ version: 9.2.1
5
+ status: relocated
6
6
  description: "Ép buộc SOLID, DRY, Clean Code với ngưỡng số liệu cụ thể — không có rule mơ hồ."
7
7
  platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
8
8
 
@@ -83,591 +83,7 @@ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
83
83
  ---
84
84
 
85
85
  # qk-engineering-standard — Code Quality Enforcer
86
-
87
- > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
88
-
89
- ## Memory Workflow
90
-
91
- ### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
92
- - 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:
93
- - **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.
94
- - **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.
95
-
96
- ---
97
-
98
- ### Pre-flight Retrieve (Trước khi thực thi)
99
- - Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
100
- bắt buộc tra cứu:
101
- - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
102
-
103
- - Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
104
- - Architecture
105
- - Hard Bug
106
- - Convention
107
- - Pattern
108
- - Tech Debt Pattern
109
- - 👉 *Domain Focus:* Convention / Architecture (vd: ngưỡng định lượng độ phức tạp cyclomatic, DRY, SOLID).
110
-
111
- - Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
112
- Không được xem Memory là Source of Truth.
113
- 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.
114
-
115
- ---
116
-
117
- ### Learning Flow (AI tự học có kiểm soát)
118
- - 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:
119
- - Hard Bug có khả năng tái diễn.
120
- - Pattern làm việc lặp lại trong dự án.
121
- - Convention hoặc quy tắc kiến trúc mới.
122
- - Quyết định Architecture quan trọng.
123
- - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
124
- - 👉 *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).
125
-
126
- - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
127
- - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
128
- - AI không được tự động Promote Candidate Memory thành Project Knowledge.
129
-
130
- ---
131
-
132
- ### Post-flight Harvest (Đề xuất → Phê duyệt)
133
- Sau khi hoàn thành task:
134
- - AI đánh giá các Candidate Memory đã tạo.
135
- - Nếu phát hiện tri thức có giá trị tái sử dụng:
136
- - Đề xuất người dùng xem xét.
137
- - Gửi yêu cầu phê duyệt thông qua:
138
- - `/learn`
139
- - `qk-project-memory`
140
- - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
141
-
142
- ```
143
- .ai-local/candidates/ ──(Approve)──> .ai-local/knowledge/index.yaml
144
- ```
145
-
146
- - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
147
- - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
148
-
149
- ---
150
-
151
- ### Ignore (Không đưa vào Memory)
152
- Không lưu:
153
- - Trace log của một session đơn lẻ.
154
- - Temporary debugging data.
155
- - Output của một lần chạy test/scan.
156
- - Report health tạm thời của một đợt kiểm tra.
157
- - Lỗi nhỏ chỉ xảy ra một lần.
158
- - Thông tin không có khả năng tái sử dụng.
159
- - 👉 *Domain Ignore:* Cảnh báo linter tạm thời.
160
-
161
- ---
162
-
163
- ### Golden Rule
164
- > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
165
- > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
166
-
167
- ---
168
-
169
-
170
-
171
- ### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
172
- - 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:
173
- - **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.
174
- - **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.
175
-
176
- ---
177
-
178
- ### Pre-flight Retrieve (Trước khi thực thi)
179
- - Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
180
- bắt buộc tra cứu:
181
- - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
182
-
183
- - Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
184
- - Architecture
185
- - Hard Bug
186
- - Convention
187
- - Pattern
188
- - Tech Debt Pattern
189
- - 👉 *Domain Focus:* Convention / Architecture (vd: ngưỡng định lượng độ phức tạp cyclomatic, DRY, SOLID).
190
-
191
- - Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
192
- Không được xem Memory là Source of Truth.
193
- 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.
194
-
195
- ---
196
-
197
- ### Learning Flow (AI tự học có kiểm soát)
198
- - 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:
199
- - Hard Bug có khả năng tái diễn.
200
- - Pattern làm việc lặp lại trong dự án.
201
- - Convention hoặc quy tắc kiến trúc mới.
202
- - Quyết định Architecture quan trọng.
203
- - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
204
- - 👉 *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).
205
-
206
- - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
207
- - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
208
- - AI không được tự động Promote Candidate Memory thành Project Knowledge.
209
-
210
- ---
211
-
212
- ### Post-flight Harvest (Đề xuất → Phê duyệt)
213
- Sau khi hoàn thành task:
214
- - AI đánh giá các Candidate Memory đã tạo.
215
- - Nếu phát hiện tri thức có giá trị tái sử dụng:
216
- - Đề xuất người dùng xem xét.
217
- - Gửi yêu cầu phê duyệt thông qua:
218
- - `/learn`
219
- - `qk-project-memory`
220
- - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
221
-
222
- ```
223
- .ai-local/candidates/ ──(Approve)──> .ai-local/knowledge/index.yaml
224
- ```
225
-
226
- - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
227
- - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
228
-
229
- ---
230
-
231
- ### Ignore (Không đưa vào Memory)
232
- Không lưu:
233
- - Trace log của một session đơn lẻ.
234
- - Temporary debugging data.
235
- - Output của một lần chạy test/scan.
236
- - Report health tạm thời của một đợt kiểm tra.
237
- - Lỗi nhỏ chỉ xảy ra một lần.
238
- - Thông tin không có khả năng tái sử dụng.
239
- - 👉 *Domain Ignore:* Cảnh báo linter tạm thời.
240
-
241
- ---
242
-
243
- ### Golden Rule
244
- > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
245
- > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
246
-
247
- ---
248
-
249
-
250
-
251
- ### Pre-flight Retrieve (Trước khi thực thi)
252
- - Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
253
- bắt buộc tra cứu:
254
- - `.agents/knowledge/index.yaml` (Shared Project Knowledge)
255
- - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
256
-
257
- - Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
258
- - Architecture
259
- - Hard Bug
260
- - Convention
261
- - Pattern
262
- - Tech Debt Pattern
263
- - 👉 *Domain Focus:* Convention / Architecture (vd: ngưỡng định lượng độ phức tạp cyclomatic, DRY, SOLID).
264
-
265
- - Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
266
- Không được xem Memory là Source of Truth.
267
- 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.
268
-
269
- ---
270
-
271
- ### Learning Flow (AI tự học có kiểm soát)
272
- - 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:
273
- - Hard Bug có khả năng tái diễn.
274
- - Pattern làm việc lặp lại trong dự án.
275
- - Convention hoặc quy tắc kiến trúc mới.
276
- - Quyết định Architecture quan trọng.
277
- - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
278
- - 👉 *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).
279
-
280
- - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
281
- - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
282
- - AI không được tự động Promote Candidate Memory thành Project Knowledge.
283
-
284
- ---
285
-
286
- ### Post-flight Harvest (Đề xuất → Phê duyệt)
287
- Sau khi hoàn thành task:
288
- - AI đánh giá các Candidate Memory đã tạo.
289
- - Nếu phát hiện tri thức có giá trị tái sử dụng:
290
- - Đề xuất người dùng xem xét.
291
- - Gửi yêu cầu phê duyệt thông qua:
292
- - `/learn`
293
- - `qk-project-memory`
294
- - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
295
-
296
- ```
297
- .ai-local/candidates/ ──(Approve)──> .agents/knowledge/index.yaml
298
- ```
299
-
300
- - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
301
- - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
302
-
303
- ---
304
-
305
- ### Ignore (Không đưa vào Memory)
306
- Không lưu:
307
- - Trace log của một session đơn lẻ.
308
- - Temporary debugging data.
309
- - Output của một lần chạy test/scan.
310
- - Report health tạm thời của một đợt kiểm tra.
311
- - Lỗi nhỏ chỉ xảy ra một lần.
312
- - Thông tin không có khả năng tái sử dụng.
313
- - 👉 *Domain Ignore:* Cảnh báo linter tạm thời.
314
-
315
- ---
316
-
317
- ### Golden Rule
318
- > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
319
- > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
320
-
321
- ---
322
- ---
323
-
324
- ### Learning Flow (AI tự học có kiểm soát)
325
- - 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:
326
- - Hard Bug có khả năng tái diễn.
327
- - Pattern làm việc lặp lại trong dự án.
328
- - Convention hoặc quy tắc kiến trúc mới.
329
- - Quyết định Architecture quan trọng.
330
- - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
331
- - 👉 *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).
332
-
333
- - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
334
- - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
335
- - AI không được tự động Promote Candidate Memory thành Project Knowledge.
336
-
337
- ---
338
-
339
- ### Post-flight Harvest (Đề xuất → Phê duyệt)
340
- Sau khi hoàn thành task:
341
- - AI đánh giá các Candidate Memory đã tạo.
342
- - Nếu phát hiện tri thức có giá trị tái sử dụng:
343
- - Đề xuất người dùng xem xét.
344
- - Gửi yêu cầu phê duyệt thông qua:
345
- - `/learn`
346
- - `qk-project-memory`
347
- - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
348
-
349
- ```
350
- .ai-local/candidates/ ──(Approve)──> .agents/knowledge/index.yaml
351
- ```
352
-
353
- - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
354
- - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
355
-
356
- ---
357
-
358
- ### Ignore (Không đưa vào Memory)
359
- Không lưu:
360
- - Trace log của một session đơn lẻ.
361
- - Temporary debugging data.
362
- - Output của một lần chạy test/scan.
363
- - Report health tạm thời của một đợt kiểm tra.
364
- - Lỗi nhỏ chỉ xảy ra một lần.
365
- - Thông tin không có khả năng tái sử dụng.
366
- - 👉 *Domain Ignore:* Cảnh báo linter tạm thời.
367
-
368
- ---
369
-
370
- ### Golden Rule
371
- > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
372
- > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
373
-
374
- ---
375
- ---
376
86
 
377
- ### Learning Flow (AI tự họckiểm soát)
378
- - 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:
379
- - Hard Bug có khả năng tái diễn.
380
- - Pattern làm việc lặp lại trong dự án.
381
- - Convention hoặc quy tắc kiến trúc mới.
382
- - Quyết định Architecture quan trọng.
383
- - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
384
- - 👉 *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).
385
-
386
- - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
387
- - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
388
- - AI không được tự động Promote Candidate Memory thành Project Knowledge.
389
-
390
- ---
391
-
392
- ### Post-flight Harvest (Đề xuất → Phê duyệt)
393
- Sau khi hoàn thành task:
394
- - AI đánh giá các Candidate Memory đã tạo.
395
- - Nếu phát hiện tri thức có giá trị tái sử dụng:
396
- - Đề xuất người dùng xem xét.
397
- - Gửi yêu cầu phê duyệt thông qua:
398
- - `/learn`
399
- - `qk-project-memory`
400
- - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
401
-
402
- ```
403
- .ai-local/candidates/ ──(Approve)──> .agents/knowledge/index.yaml
404
- ```
405
-
406
- - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
407
- - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
408
-
409
- ---
410
-
411
- ### Ignore (Không đưa vào Memory)
412
- Không lưu:
413
- - Trace log của một session đơn lẻ.
414
- - Temporary debugging data.
415
- - Output của một lần chạy test/scan.
416
- - Report health tạm thời của một đợt kiểm tra.
417
- - Lỗi nhỏ chỉ xảy ra một lần.
418
- - Thông tin không có khả năng tái sử dụng.
419
- - 👉 *Domain Ignore:* Cảnh báo linter tạm thời.
420
-
421
- ---
422
-
423
- ### Golden Rule
424
- > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
425
- > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
426
-
427
- ---
428
- ---
429
- ---
430
- ---
431
-
432
- ## Preconditions
433
- - [ ] Target file(s) or module(s) are specified
434
-
435
- ```
436
- On missing precondition:
437
- EXIT: BLOCKED
438
- Message: "Vui lòng chỉ định file hoặc module cần kiểm tra."
439
- ```
440
-
441
- ## Scope
442
- - ✅ Detect violations with exact file:line references
443
- - ✅ Classify by severity with concrete thresholds
444
- - ✅ Suggest minimal, targeted refactors
445
-
446
- ## Non-Goals
447
- - ❌ Auto-fix code — report only (fixes go to qk-bug-resolution or qk-feature-delivery)
448
- - ❌ Rewrite architecture
449
- - ❌ Touch files outside the specified scope
450
-
451
- ## Concrete Thresholds (Non-Negotiable)
452
- **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):**
453
-
454
- ```yaml
455
- function:
456
- max_lines: 30 # Lines of code, excluding comments/blanks
457
- max_cyclomatic_complexity: 10
458
- max_parameters: 4
459
-
460
- file:
461
- max_lines: 300
462
- max_public_methods_per_class: 10 # God Class threshold
463
-
464
- dry:
465
- violation_threshold: 3 # Same logic duplicated in ≥ 3 places
466
-
467
- separation_of_concerns:
468
- violation: "File mixes UI rendering + API calls + State management"
469
-
470
- naming:
471
- min_variable_name_length: 2 # Single-letter vars (except i,j,k in loops)
472
- max_abbreviation_ratio: 0.3 # > 30% abbreviations in identifiers = violation
473
-
474
- dependency:
475
- max_imports_per_file: 15 # Beyond this: likely a God File
476
- ```
477
-
478
- ## Priority Order
479
-
480
- | Priority | Check | Severity | Skip Threshold |
481
- |----------|-------|----------|----------------|
482
- | P1 | Security violations (hardcoded secrets, SQL injection) | CRITICAL | Never |
483
- | P2 | God Functions > 30 lines / complexity > 10 | HIGH | Budget < 30% |
484
- | P3 | God Files > 300 lines / God Classes | HIGH | Budget < 40% |
485
- | P4 | DRY violations (3+ duplicates) | MEDIUM | Budget < 50% |
486
- | P5 | Mixed concerns in single file | MEDIUM | Budget < 60% |
487
- | P6 | Naming convention violations | LOW | Budget < 70% |
488
- | P7 | Excessive imports / coupling | LOW | Budget < 80% |
489
-
490
- ## Workflow
491
-
492
- ### Phase 1 — Scan for Critical & High Violations
493
-
494
- **Steps:**
495
- 1. `grep_search` — search for: hardcoded secrets, `console.log`, `eval(`, `any` types
496
- 2. `view_file[targeted]` — read function definitions to count lines and parameters
497
- 3. Log each violation with Evidence Format
498
-
499
- **Decision:**
500
- ```
501
- IF CRITICAL violation found (e.g., hardcoded API key)
502
- → Report immediately, mark EXIT: FAILED
503
- → Still continue scanning (don't stop at first critical)
504
-
505
- IF function line count > 30 OR complexity > 10
506
- → Log as [HIGH]
507
-
508
- IF file line count > 300
509
- → Log as [HIGH] — God File suspected
510
- ```
511
-
512
- **Exit When:**
513
- - All P1+P2+P3 checks done → go to Phase 2
514
- - Token budget < 30% → go to Phase 3 directly with PARTIAL flag
515
-
516
- ### Phase 2 — Scan for Medium & Low Violations
517
-
518
- **Steps:**
519
- 1. `grep_search` — find duplicate logic patterns (copy-paste code)
520
- 2. Check import counts per file
521
- 3. Check naming conventions
522
-
523
- **Decision:**
524
- ```
525
- IF same logic block appears ≥ 3 times
526
- → Log as [MEDIUM] DRY violation
527
-
528
- IF file has > 15 imports
529
- → Log as [LOW] — potential God File or tight coupling
530
-
531
- IF token budget < 50%
532
- → Skip P6+P7, go to Phase 3
533
- ```
534
-
535
- ### Phase 3 — Score & Report
536
-
537
- **Steps:**
538
- 1. Count violations by severity
539
- 2. Calculate health score: start at 100, deduct per violation
540
- 3. Generate report
541
-
542
- **Deduction Scale:**
543
- ```
544
- CRITICAL: -25 pts each
545
- HIGH: -10 pts each
546
- MEDIUM: -5 pts each
547
- LOW: -2 pts each
548
- ```
549
-
550
- **Decision:**
551
- ```
552
- IF score ≥ 80 AND no CRITICAL violations
553
- → EXIT: SUCCESS
554
-
555
- IF score 60–79 OR any HIGH violations
556
- → EXIT: PARTIAL — list fixes needed
557
-
558
- IF score < 60 OR any CRITICAL violations
559
- → EXIT: FAILED — requires immediate action
560
- ```
561
-
562
- ## Confidence Model
563
-
564
- | Level | Condition | Action |
565
- |-------|-----------|--------|
566
- | HIGH | Direct line count, exact pattern match | Report as violation |
567
- | MEDIUM | Inferred cyclomatic complexity without tool | Note estimate |
568
- | LOW | Architectural smell inferred from structure | Mark as "suspected — verify manually" |
569
-
570
- ## Severity
571
-
572
- | Level | Definition | Example |
573
- |-------|-----------|---------|
574
- | CRITICAL | Security risk or data integrity | Hardcoded secret, SQL injection via string concat |
575
- | HIGH | Technical debt that blocks scaling | Function 80 lines, God Class 15+ methods |
576
- | MEDIUM | DRY or SoC violation, fixable in < 1 hour | Same validation logic in 3 components |
577
- | LOW | Style/naming issue, non-blocking | Single-letter variable `x` outside loop |
578
-
579
- ## Evidence Format
580
-
581
- ```
582
- [SEVERITY] path/to/file.ts:LINE
583
- Rule: [FUNCTION_LENGTH | COMPLEXITY | DRY | SOC | NAMING | GOD_CLASS | SECRET]
584
- Reason: [specific measurement vs threshold]
585
- Confidence: [HIGH|MEDIUM|LOW]
586
- Fix: [one-line suggestion]
587
- Deduction: -N pts
588
- ```
589
-
590
- **Example:**
591
- ```
592
- [HIGH] src/services/order.service.ts:45
593
- Rule: FUNCTION_LENGTH
594
- Reason: Function `processOrder` is 87 lines (threshold: 30)
595
- Confidence: HIGH
596
- Fix: Extract payment logic to `processPayment()`, shipping to `scheduleShipment()`
597
- Deduction: -10 pts
598
- ```
599
-
600
- ## Retry Policy
601
- ```
602
- Audit is read-only — no retry needed.
603
- If file is inaccessible → skip and note in report as PARTIAL.
604
- ```
605
-
606
- ## Escalation Rules
607
-
608
- ```
609
- BLOCKED: No target specified
610
- Missing:
611
- - File path or module name to audit
612
- Questions:
613
- 1. Bạn muốn kiểm tra file nào hoặc toàn bộ module nào?
614
- 2. Có ngưỡng cụ thể nào bạn muốn thay đổi không? (mặc định: 30 lines/function)
615
- ```
616
-
617
- ## Handoff Contract
618
-
619
- ### Consumes
620
- ```json
621
- {
622
- "from": "user or qk-orchestrator",
623
- "required_fields": ["target_files_or_module"],
624
- "optional_fields": ["custom_thresholds"]
625
- }
626
- ```
627
-
628
- ### Produces
629
- ```json
630
- {
631
- "to": "user",
632
- "output_fields": ["health_score", "violations_list", "severity_counts", "exit_code"]
633
- }
634
- ```
635
-
636
- ## Output Format
637
-
638
- ```
639
- ⚙️ Engineering Standard Audit
640
- ─────────────────────────────────────────────────
641
- Target: [file or module]
642
-
643
- Health Score: [X/100]
644
- CRITICAL violations: [N] (-Npts)
645
- HIGH violations: [N] (-Npts)
646
- MEDIUM violations: [N] (-Npts)
647
- LOW violations: [N] (-Npts)
648
-
649
- Violations (priority order):
650
- [SEVERITY] file:LINE — Rule — reason — Fix — (-Xpts)
651
-
652
- Required Actions:
653
- 1. [Most critical fix]
654
- 2. [Second fix]
655
-
656
- Exit Code: [SUCCESS | PARTIAL | FAILED]
657
- ```
658
-
659
- ## Exit Codes
660
-
661
- | Code | Meaning | When |
662
- |------|---------|------|
663
- | SUCCESS | Score ≥ 80, no CRITICAL | Code meets V7.5 standards |
664
- | PARTIAL | Score 60–79 or incomplete scan | Some categories skipped |
665
- | BLOCKED | No target specified | Cannot audit without scope |
666
- | FAILED | Score < 60 or CRITICAL found | Immediate action required |
667
-
668
- ## References
669
- - Detailed thresholds with rationale: `references/thresholds.md`
670
- - Anti-Patterns Blacklist: `references/anti-patterns.md`
671
-
672
- ---
87
+ > **⚠️ 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 `side_effects: edit_files`.
673
88
 
89
+ > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.