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-validation-gate
4
- version: 9.1.0
5
- status: stable
4
+ version: 9.2.1
5
+ status: relocated
6
6
  description: "Cổng kiểm tra chất lượng & Eval Pipeline bắt buộc — chạy linters, tests, và đánh giá scorecard.yaml định lượng cho AI Agent."
7
7
  platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
8
8
 
@@ -82,606 +82,7 @@ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
82
82
  ---
83
83
 
84
84
  # qk-validation-gate — Quality Gate
85
-
86
- > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
87
-
88
- ## Memory Workflow
89
-
90
- ### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
91
- - 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:
92
- - **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.
93
- - **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.
94
-
95
- ---
96
-
97
- ### Pre-flight Retrieve (Trước khi thực thi)
98
- - Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
99
- bắt buộc tra cứu:
100
- - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
101
-
102
- - Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
103
- - Architecture
104
- - Hard Bug
105
- - Convention
106
- - Pattern
107
- - Tech Debt Pattern
108
- - 👉 *Domain Focus:* Convention / Architecture (vd: các ngưỡng scorecard, quy định zero hallucination).
109
-
110
- - Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
111
- Không được xem Memory là Source of Truth.
112
- 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.
113
-
114
- ---
115
-
116
- ### Learning Flow (AI tự học có kiểm soát)
117
- - 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:
118
- - Hard Bug có khả năng tái diễn.
119
- - Pattern làm việc lặp lại trong dự án.
120
- - Convention hoặc quy tắc kiến trúc mới.
121
- - Quyết định Architecture quan trọng.
122
- - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
123
- - 👉 *Domain Harvest:* Bộ tiêu chí kiểm định mới (Scorecard metric) được tích hợp vào pipeline.
124
-
125
- - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
126
- - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
127
- - AI không được tự động Promote Candidate Memory thành Project Knowledge.
128
-
129
- ---
130
-
131
- ### Post-flight Harvest (Đề xuất → Phê duyệt)
132
- Sau khi hoàn thành task:
133
- - AI đánh giá các Candidate Memory đã tạo.
134
- - Nếu phát hiện tri thức có giá trị tái sử dụng:
135
- - Đề xuất người dùng xem xét.
136
- - Gửi yêu cầu phê duyệt thông qua:
137
- - `/learn`
138
- - `qk-project-memory`
139
- - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
140
-
141
- ```
142
- .ai-local/candidates/ ──(Approve)──> .ai-local/knowledge/index.yaml
143
- ```
144
-
145
- - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
146
- - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
147
-
148
- ---
149
-
150
- ### Ignore (Không đưa vào Memory)
151
- Không lưu:
152
- - Trace log của một session đơn lẻ.
153
- - Temporary debugging data.
154
- - Output của một lần chạy test/scan.
155
- - Report health tạm thời của một đợt kiểm tra.
156
- - Lỗi nhỏ chỉ xảy ra một lần.
157
- - Thông tin không có khả năng tái sử dụng.
158
- - 👉 *Domain Ignore:* Kết quả log pass/fail tạm thời của một build con.
159
-
160
- ---
161
-
162
- ### Golden Rule
163
- > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
164
- > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
165
-
166
- ---
167
-
168
-
169
-
170
- ### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
171
- - 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:
172
- - **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.
173
- - **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.
174
-
175
- ---
176
-
177
- ### Pre-flight Retrieve (Trước khi thực thi)
178
- - Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
179
- bắt buộc tra cứu:
180
- - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
181
-
182
- - Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
183
- - Architecture
184
- - Hard Bug
185
- - Convention
186
- - Pattern
187
- - Tech Debt Pattern
188
- - 👉 *Domain Focus:* Convention / Architecture (vd: các ngưỡng scorecard, quy định zero hallucination).
189
-
190
- - Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
191
- Không được xem Memory là Source of Truth.
192
- 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.
193
-
194
- ---
195
-
196
- ### Learning Flow (AI tự học có kiểm soát)
197
- - 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:
198
- - Hard Bug có khả năng tái diễn.
199
- - Pattern làm việc lặp lại trong dự án.
200
- - Convention hoặc quy tắc kiến trúc mới.
201
- - Quyết định Architecture quan trọng.
202
- - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
203
- - 👉 *Domain Harvest:* Bộ tiêu chí kiểm định mới (Scorecard metric) được tích hợp vào pipeline.
204
-
205
- - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
206
- - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
207
- - AI không được tự động Promote Candidate Memory thành Project Knowledge.
208
-
209
- ---
210
-
211
- ### Post-flight Harvest (Đề xuất → Phê duyệt)
212
- Sau khi hoàn thành task:
213
- - AI đánh giá các Candidate Memory đã tạo.
214
- - Nếu phát hiện tri thức có giá trị tái sử dụng:
215
- - Đề xuất người dùng xem xét.
216
- - Gửi yêu cầu phê duyệt thông qua:
217
- - `/learn`
218
- - `qk-project-memory`
219
- - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
220
-
221
- ```
222
- .ai-local/candidates/ ──(Approve)──> .ai-local/knowledge/index.yaml
223
- ```
224
-
225
- - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
226
- - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
227
-
228
- ---
229
-
230
- ### Ignore (Không đưa vào Memory)
231
- Không lưu:
232
- - Trace log của một session đơn lẻ.
233
- - Temporary debugging data.
234
- - Output của một lần chạy test/scan.
235
- - Report health tạm thời của một đợt kiểm tra.
236
- - Lỗi nhỏ chỉ xảy ra một lần.
237
- - Thông tin không có khả năng tái sử dụng.
238
- - 👉 *Domain Ignore:* Kết quả log pass/fail tạm thời của một build con.
239
-
240
- ---
241
-
242
- ### Golden Rule
243
- > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
244
- > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
245
-
246
- ---
247
-
248
-
249
-
250
- ### Pre-flight Retrieve (Trước khi thực thi)
251
- - Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
252
- bắt buộc tra cứu:
253
- - `.agents/knowledge/index.yaml` (Shared Project Knowledge)
254
- - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
255
-
256
- - Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
257
- - Architecture
258
- - Hard Bug
259
- - Convention
260
- - Pattern
261
- - Tech Debt Pattern
262
- - 👉 *Domain Focus:* Convention / Architecture (vd: các ngưỡng scorecard, quy định zero hallucination).
263
-
264
- - Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
265
- Không được xem Memory là Source of Truth.
266
- 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.
267
-
268
- ---
269
-
270
- ### Learning Flow (AI tự học có kiểm soát)
271
- - 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:
272
- - Hard Bug có khả năng tái diễn.
273
- - Pattern làm việc lặp lại trong dự án.
274
- - Convention hoặc quy tắc kiến trúc mới.
275
- - Quyết định Architecture quan trọng.
276
- - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
277
- - 👉 *Domain Harvest:* Bộ tiêu chí kiểm định mới (Scorecard metric) được tích hợp vào pipeline.
278
-
279
- - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
280
- - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
281
- - AI không được tự động Promote Candidate Memory thành Project Knowledge.
282
-
283
- ---
284
-
285
- ### Post-flight Harvest (Đề xuất → Phê duyệt)
286
- Sau khi hoàn thành task:
287
- - AI đánh giá các Candidate Memory đã tạo.
288
- - Nếu phát hiện tri thức có giá trị tái sử dụng:
289
- - Đề xuất người dùng xem xét.
290
- - Gửi yêu cầu phê duyệt thông qua:
291
- - `/learn`
292
- - `qk-project-memory`
293
- - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
294
-
295
- ```
296
- .ai-local/candidates/ ──(Approve)──> .agents/knowledge/index.yaml
297
- ```
298
-
299
- - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
300
- - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
301
-
302
- ---
303
-
304
- ### Ignore (Không đưa vào Memory)
305
- Không lưu:
306
- - Trace log của một session đơn lẻ.
307
- - Temporary debugging data.
308
- - Output của một lần chạy test/scan.
309
- - Report health tạm thời của một đợt kiểm tra.
310
- - Lỗi nhỏ chỉ xảy ra một lần.
311
- - Thông tin không có khả năng tái sử dụng.
312
- - 👉 *Domain Ignore:* Kết quả log pass/fail tạm thời của một build con.
313
-
314
- ---
315
-
316
- ### Golden Rule
317
- > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
318
- > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
319
-
320
- ---
321
- ---
322
-
323
- ### Learning Flow (AI tự học có kiểm soát)
324
- - 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:
325
- - Hard Bug có khả năng tái diễn.
326
- - Pattern làm việc lặp lại trong dự án.
327
- - Convention hoặc quy tắc kiến trúc mới.
328
- - Quyết định Architecture quan trọng.
329
- - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
330
- - 👉 *Domain Harvest:* Bộ tiêu chí kiểm định mới (Scorecard metric) được tích hợp vào pipeline.
331
-
332
- - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
333
- - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
334
- - AI không được tự động Promote Candidate Memory thành Project Knowledge.
335
-
336
- ---
337
-
338
- ### Post-flight Harvest (Đề xuất → Phê duyệt)
339
- Sau khi hoàn thành task:
340
- - AI đánh giá các Candidate Memory đã tạo.
341
- - Nếu phát hiện tri thức có giá trị tái sử dụng:
342
- - Đề xuất người dùng xem xét.
343
- - Gửi yêu cầu phê duyệt thông qua:
344
- - `/learn`
345
- - `qk-project-memory`
346
- - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
347
-
348
- ```
349
- .ai-local/candidates/ ──(Approve)──> .agents/knowledge/index.yaml
350
- ```
351
-
352
- - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
353
- - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
354
-
355
- ---
356
-
357
- ### Ignore (Không đưa vào Memory)
358
- Không lưu:
359
- - Trace log của một session đơn lẻ.
360
- - Temporary debugging data.
361
- - Output của một lần chạy test/scan.
362
- - Report health tạm thời của một đợt kiểm tra.
363
- - Lỗi nhỏ chỉ xảy ra một lần.
364
- - Thông tin không có khả năng tái sử dụng.
365
- - 👉 *Domain Ignore:* Kết quả log pass/fail tạm thời của một build con.
366
-
367
- ---
368
-
369
- ### Golden Rule
370
- > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
371
- > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
372
-
373
- ---
374
- ---
375
-
376
- ### Learning Flow (AI tự học có kiểm soát)
377
- - 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:
378
- - Hard Bug có khả năng tái diễn.
379
- - Pattern làm việc lặp lại trong dự án.
380
- - Convention hoặc quy tắc kiến trúc mới.
381
- - Quyết định Architecture quan trọng.
382
- - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
383
- - 👉 *Domain Harvest:* Bộ tiêu chí kiểm định mới (Scorecard metric) được tích hợp vào pipeline.
384
-
385
- - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
386
- - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
387
- - AI không được tự động Promote Candidate Memory thành Project Knowledge.
388
85
 
389
- ---
390
-
391
- ### Post-flight Harvest (Đề xuất → Phê duyệt)
392
- Sau khi hoàn thành task:
393
- - AI đánh giá các Candidate Memory đã tạo.
394
- - Nếu phát hiện tri thức có giá trị tái sử dụng:
395
- - Đề xuất người dùng xem xét.
396
- - Gửi yêu cầu phê duyệt thông qua:
397
- - `/learn`
398
- - `qk-project-memory`
399
- - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
400
-
401
- ```
402
- .ai-local/candidates/ ──(Approve)──> .agents/knowledge/index.yaml
403
- ```
404
-
405
- - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
406
- - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
407
-
408
- ---
409
-
410
- ### Ignore (Không đưa vào Memory)
411
- Không lưu:
412
- - Trace log của một session đơn lẻ.
413
- - Temporary debugging data.
414
- - Output của một lần chạy test/scan.
415
- - Report health tạm thời của một đợt kiểm tra.
416
- - Lỗi nhỏ chỉ xảy ra một lần.
417
- - Thông tin không có khả năng tái sử dụng.
418
- - 👉 *Domain Ignore:* Kết quả log pass/fail tạm thời của một build con.
419
-
420
- ---
421
-
422
- ### Golden Rule
423
- > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
424
- > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
425
-
426
- ---
427
- ---
428
- ---
429
- ---
430
-
431
- ## Preconditions
432
- - [ ] Project has `package.json` with lint/test scripts (or equivalent for other runtimes)
433
- - [ ] Target scope is specified (specific files, or whole project)
434
-
435
- ```
436
- On missing precondition:
437
- EXIT: BLOCKED
438
- Message: "Không tìm thấy script lint/test. Vui lòng chỉ định lệnh kiểm tra."
439
- ```
440
-
441
- ## Scope & V8.2 Eval Pipeline
442
- - ✅ Run lint, type-check, tests, and security audit in sequence
443
- - ✅ **Execute V8.2 Eval Pipeline:** Read `scorecard.yaml` (or inherited schemas) and compute quantitative scores for AI/Agent outputs.
444
- - ✅ Enforce pass/fail with concrete thresholds (Code coverage >= 80%, Eval scorecard >= passing threshold, typically 80/100).
445
- - ✅ Validate Trace execution logs in `evals/traces/` to ensure zero hallucination and ground-truth compliance.
446
- - ✅ Report results with structured Evidence Format.
447
-
448
- ## Non-Goals
449
- - ❌ Fix failing tests or lint errors (fixes go to qk-bug-resolution)
450
- - ❌ Skip any gate check or eval scorecard unless user explicitly allows
451
- - ❌ Override failing thresholds with "ignore" flags or fabricated LLM scores without trace evidence
452
-
453
- ## Pass/Fail Thresholds (Non-Negotiable)
454
-
455
- ```yaml
456
- lint:
457
- errors: 0 # Zero tolerance for lint errors
458
- warnings: allowed # Warnings do not block
459
-
460
- typescript:
461
- errors: 0 # Zero type errors
462
-
463
- tests:
464
- coverage_minimum: 80% # Overall coverage
465
- unit_test_pass_rate: 100% # All unit tests must pass
466
- integration_test_pass_rate: 100%
467
-
468
- security:
469
- critical_vulnerabilities: 0
470
- high_vulnerabilities: 0
471
- medium_vulnerabilities: 5 # Max allowed (review required)
472
-
473
- build:
474
- must_succeed: true
475
- max_warnings: 5
476
- bundle_size_limit: 500KB # Gzipped (if applicable)
477
-
478
- eval_scorecard:
479
- default_passing_threshold: 80 # minimum weighted evaluation score
480
- trace_verification_required: true # must log tool executions in evals/traces
481
- zero_tolerance_hallucination: true
482
- ```
483
-
484
- ## Priority Order
485
-
486
- | Priority | Gate | Fail = Block? | Skip Allowed? |
487
- |----------|------|---------------|---------------|
488
- | P1 | Security audit (`npm audit`) | YES | Never |
489
- | P2 | TypeScript / type check | YES | Never |
490
- | P3 | Lint (errors only) | YES | Never |
491
- | P4 | Unit tests | YES | Never |
492
- | P5 | Integration tests | YES | Only if no integration tests exist |
493
- | P6 | Coverage check | YES if < 80% | Never |
494
- | P7 | Build | YES | Never |
495
- | P8 | Bundle size | WARN only | Budget < 80% |
496
-
497
- ## Workflow
498
-
499
- ### Phase 1 — Security Gate (P1)
500
-
501
- **Steps:**
502
- 1. Run: `npm audit --audit-level=high` (or equivalent)
503
- 2. Parse output for CRITICAL and HIGH
504
-
505
- **Decision:**
506
- ```
507
- IF 0 critical + 0 high
508
- → PASS P1 → go to Phase 2
509
-
510
- ELSE IF critical or high found
511
- → EXIT: FAILED immediately
512
- → Report: exact package name, CVE, severity
513
- ```
514
-
515
- ### Phase 2 — Type & Lint Gate (P2+P3)
516
-
517
- **Steps:**
518
- 1. Run: `npm run typecheck` (or `tsc --noEmit`)
519
- 2. Run: `npm run lint`
520
- 3. Parse error counts
521
-
522
- **Decision:**
523
- ```
524
- IF 0 type errors AND 0 lint errors
525
- → PASS P2+P3 → go to Phase 3
526
-
527
- ELSE IF type errors > 0
528
- → EXIT: FAILED — list each error with file:line
529
-
530
- ELSE IF lint errors > 0 (warnings OK)
531
- → EXIT: FAILED — list errors
532
- ```
533
-
534
- ### Phase 3 — Test Gate (P4+P5+P6)
535
-
536
- **Steps:**
537
- 1. Run: `npm test -- --coverage` (or equivalent)
538
- 2. Parse: pass/fail counts, coverage percentage
539
-
540
- **Decision:**
541
- ```
542
- IF all tests pass AND coverage ≥ 80%
543
- → PASS P4+P5+P6 → go to Phase 4
544
-
545
- ELSE IF any test fails
546
- → EXIT: FAILED — list failing test names
547
-
548
- ELSE IF coverage < 80%
549
- → EXIT: FAILED — show coverage report (file-level)
550
- ```
551
-
552
- **Retry Policy:**
553
- ```
554
- Test fail
555
- └─ Check if it's a flaky test (run once more)
556
- ├─ PASS on retry → note "flaky test detected", continue
557
- └─ FAIL on retry → EXIT: FAILED — not flaky, real failure
558
- ```
559
-
560
- ### Phase 4 — Build Gate (P7)
561
-
562
- **Steps:**
563
- 1. Run: `npm run build`
564
- 2. Check exit code + warnings count
565
-
566
- **Decision:**
567
- ```
568
- IF build succeeds AND warnings ≤ 5
569
- → EXIT: SUCCESS
570
-
571
- ELSE IF build fails
572
- → EXIT: FAILED
573
-
574
- ELSE IF warnings > 5
575
- → EXIT: PARTIAL — list warnings, continue to release if user confirms
576
- ```
577
-
578
- ## Confidence Model
579
-
580
- | Level | Condition | Action |
581
- |-------|-----------|--------|
582
- | HIGH | Command exit code 0/non-0, numeric output | Report directly |
583
- | MEDIUM | Inferred from partial output (truncated logs) | Note potential missing info |
584
- | LOW | Script not found or output format unknown | EXIT: BLOCKED — clarify commands |
585
-
586
- ## Severity
587
-
588
- | Level | Definition | Example |
589
- |-------|-----------|---------|
590
- | CRITICAL | Security vulnerability in production dependency | CVE in auth library |
591
- | HIGH | Type error or failing test | `Cannot read property of undefined` |
592
- | MEDIUM | Coverage below threshold | 67% coverage (threshold 80%) |
593
- | LOW | Build warning | Unused export |
594
-
595
- ## Evidence Format
596
-
597
- ```
598
- [SEVERITY] Gate: [SECURITY|TYPE|LINT|TEST|COVERAGE|BUILD]
599
- Command: [command that was run]
600
- Result: [PASS | FAIL — exact output snippet]
601
- Threshold: [what the threshold is]
602
- Actual: [what was measured]
603
- Fix: [where to look for the fix]
604
- ```
605
-
606
- **Example:**
607
- ```
608
- [HIGH] Gate: TEST
609
- Command: npm test -- --coverage
610
- Result: FAIL — 3 tests failed
611
- Threshold: 100% pass rate
612
- Actual: 47/50 tests passed
613
- Fix: See failing tests: auth.test.ts:L45, user.test.ts:L23, order.test.ts:L89
614
- ```
615
-
616
- ## Escalation Rules
617
-
618
- ```
619
- BLOCKED: Cannot run validation
620
- Missing:
621
- - npm scripts (lint, test, build) in package.json
622
- - OR test framework setup
623
- Questions:
624
- 1. Dùng lệnh gì để chạy lint? (e.g., eslint, biome, oxlint)
625
- 2. Dùng lệnh gì để chạy test? (e.g., vitest, jest, playwright)
626
- 3. Coverage threshold dự án quy định là bao nhiêu?
627
- Recommended Assumptions:
628
- - Standard: npm run lint + npm test + npm run build
629
- ```
630
-
631
- ## Handoff Contract
632
-
633
- ### Consumes
634
- ```json
635
- {
636
- "from": "user or qk-orchestrator",
637
- "required_fields": ["project_root"],
638
- "optional_fields": ["custom_commands", "custom_thresholds", "scope_files"]
639
- }
640
- ```
641
-
642
- ### Produces
643
- ```json
644
- {
645
- "to": "qk-production-release (if all pass)",
646
- "output_fields": ["gate_results", "coverage_percent", "violations_list", "exit_code"]
647
- }
648
- ```
649
-
650
- ## Output Format
651
-
652
- ```
653
- 🔒 Validation Gate Report
654
- ─────────────────────────────────────────────────
655
- Project: [path]
656
-
657
- Gate Results:
658
- P1 Security: [✅ PASS | ❌ FAIL — N critical, N high]
659
- P2 TypeScript: [✅ PASS | ❌ FAIL — N errors]
660
- P3 Lint: [✅ PASS | ❌ FAIL — N errors (N warnings)]
661
- P4 Unit Tests: [✅ PASS | ❌ FAIL — N/N passed]
662
- P5 Integration: [✅ PASS | ❌ FAIL | ⏭️ SKIPPED]
663
- P6 Coverage: [✅ PASS (N%) | ❌ FAIL (N% < 80%)]
664
- P7 Build: [✅ PASS | ❌ FAIL]
665
-
666
- Failures (action required):
667
- [SEVERITY] Gate — detail — Fix hint
668
-
669
- Exit Code: [SUCCESS | PARTIAL | BLOCKED | FAILED]
670
- ```
671
-
672
- ---
673
-
674
- ## Retry Policy
675
-
676
- ---
677
- ## Exit Codes
678
-
679
- | Code | Meaning | When |
680
- |------|---------|------|
681
- | SUCCESS | All gates passed, thresholds met | Safe to proceed to release |
682
- | PARTIAL | Build pass, but warnings > 5 OR integration skipped | User confirmation required |
683
- | BLOCKED | Cannot run — missing scripts or config | Setup required |
684
- | FAILED | Any gate failed at threshold | Do NOT release — fix first |
685
-
686
- ---
86
+ > **⚠️ ARCHIVED (v9.2.1):** Downgraded thành workflow step. Logic verify đã được embed vào step `verify` của `feature-delivery.yml`, `bug-resolution.yml`, `refactor.yml`. Không cần gọi trực tiếp.
687
87
 
88
+ > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.