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.
- package/.agents/AGENTS.md +139 -42
- package/.agents/DEV_PROFILE.md +95 -0
- package/.agents/registry/capability-graph.yml +171 -334
- package/.agents/registry/graph.json +37 -19
- package/.agents/registry/index.yaml +59 -13
- package/.agents/registry/skills-index.yml +204 -447
- package/.agents/rules/coding.md +23 -0
- package/.agents/rules/global.md +44 -30
- package/.agents/skills/_template/SKILL.md +2 -377
- package/.agents/skills/qk-access-policy/SKILL.md +98 -473
- package/.agents/skills/qk-agent-observability/SKILL.md +3 -439
- package/.agents/skills/qk-ai-builder/SKILL.md +132 -565
- package/.agents/skills/qk-api-consumer/SKILL.md +256 -0
- package/.agents/skills/qk-api-consumer/capability.yaml +21 -0
- package/.agents/skills/qk-api-consumer/evals/scorecard.yaml +29 -0
- package/.agents/skills/qk-api-lifecycle/SKILL.md +133 -456
- package/.agents/skills/qk-bug-resolution/SKILL.md +128 -561
- package/.agents/skills/qk-code-review/SKILL.md +142 -420
- package/.agents/skills/qk-context-loader/SKILL.md +99 -471
- package/.agents/skills/qk-data-engineer/SKILL.md +119 -340
- package/.agents/skills/qk-data-lifecycle/SKILL.md +89 -488
- package/.agents/skills/qk-db-optimizer/SKILL.md +102 -488
- package/.agents/skills/qk-design-system-engineering/SKILL.md +76 -461
- package/.agents/skills/qk-devops-platform/SKILL.md +77 -463
- package/.agents/skills/qk-docs/SKILL.md +88 -494
- package/.agents/skills/qk-engineering-standard/SKILL.md +4 -588
- package/.agents/skills/qk-fe-api-integration/SKILL.md +343 -343
- package/.agents/skills/qk-fe-api-integration/evals/scorecard.yaml +29 -29
- package/.agents/skills/qk-feature-delivery/SKILL.md +137 -445
- package/.agents/skills/qk-feature-delivery/evals/scorecard.yaml +1 -1
- package/.agents/skills/qk-frontend-architecture/SKILL.md +5 -479
- package/.agents/skills/qk-help/evals/scorecard.yaml +13 -13
- package/.agents/skills/qk-orchestrator/SKILL.md +63 -502
- package/.agents/skills/qk-orchestrator/references/routing-table.md +10 -14
- package/.agents/skills/qk-product-specification/SKILL.md +70 -479
- package/.agents/skills/qk-production-release/SKILL.md +80 -537
- package/.agents/skills/qk-project-audit/SKILL.md +174 -0
- package/.agents/skills/qk-project-bootstrap/SKILL.md +243 -471
- package/.agents/skills/qk-project-health/SKILL.md +97 -496
- package/.agents/skills/qk-project-memory/SKILL.md +76 -21
- package/.agents/skills/qk-refactor/SKILL.md +167 -384
- package/.agents/skills/qk-security-audit/SKILL.md +141 -463
- package/.agents/skills/qk-security-audit/capability.yaml +1 -2
- package/.agents/skills/qk-system-evolution/SKILL.md +343 -343
- package/.agents/skills/qk-system-evolution/evals/scorecard.yaml +26 -26
- package/.agents/skills/qk-test-engineering/SKILL.md +119 -509
- package/.agents/skills/qk-ui-audit/SKILL.md +73 -537
- package/.agents/skills/qk-ui-builder/SKILL.md +521 -482
- package/.agents/skills/qk-ui-system-builder/SKILL.md +68 -514
- package/.agents/skills/qk-upgrade/SKILL.md +301 -0
- package/.agents/skills/qk-upgrade/capability.yaml +24 -0
- package/.agents/skills/qk-upgrade/evals/scorecard.yaml +26 -0
- package/.agents/skills/qk-validation-gate/SKILL.md +4 -603
- package/.agents/skills/qk-web-quality-gate/SKILL.md +85 -463
- package/.agents/workflows/bug-resolution.yml +6 -6
- package/.agents/workflows/context-discovery.yml +94 -0
- package/.agents/workflows/feature-delivery.yml +8 -4
- package/.agents/workflows/refactor.yml +6 -3
- package/.agents/workflows/shared/quality-gate.yml +94 -0
- package/.agents/workflows/skin-governance.yml +115 -0
- package/README.md +152 -67
- package/package.json +2 -2
- 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
|
|
5
|
-
status:
|
|
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.
|