ai-developer-skill-os 9.3.1 → 10.1.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 (185) hide show
  1. package/.agents/AGENTS.md +60 -40
  2. package/.agents/DEV_PROFILE.md +36 -2
  3. package/.agents/registry/graph.json +95 -342
  4. package/.agents/registry/index.yaml +61 -237
  5. package/.agents/rules/coding.md +30 -12
  6. package/.agents/rules/command-safety.md +19 -8
  7. package/.agents/rules/global.md +234 -28
  8. package/.agents/rules/prompt-compiler.md +170 -0
  9. package/.agents/skills/qk-api-data-discovery/SKILL.md +470 -0
  10. package/.agents/skills/qk-backend-data/SKILL.md +190 -0
  11. package/.agents/skills/qk-bug-resolution/SKILL.md +176 -248
  12. package/.agents/skills/qk-code-cleaner/SKILL.md +250 -0
  13. package/.agents/skills/qk-code-review/SKILL.md +126 -247
  14. package/.agents/skills/qk-devops-release/SKILL.md +145 -0
  15. package/.agents/skills/qk-feature-delivery/SKILL.md +179 -247
  16. package/.agents/skills/qk-orchestrator/SKILL.md +100 -151
  17. package/.agents/skills/qk-product-spec/SKILL.md +113 -0
  18. package/.agents/skills/qk-prompt-compiler/SKILL.md +321 -0
  19. package/.agents/skills/qk-ui-engineer/SKILL.md +137 -0
  20. package/.agents/workflows/feature-delivery.yml +1 -1
  21. package/.agents/workflows/production-release.yml +1 -1
  22. package/.agents/workflows/spec-driven-development.yml +109 -87
  23. package/CHANGELOG.md +16 -0
  24. package/README.md +125 -205
  25. package/bin/install.js +337 -329
  26. package/package.json +2 -2
  27. package/.agents/README.md +0 -90
  28. package/.agents/docs/CHI_TIET_SKILLS.md +0 -126
  29. package/.agents/docs/HUONG_DAN_SU_DUNG.md +0 -120
  30. package/.agents/docs/MIGRATION-CLEANUP-V8.1.3.md +0 -36
  31. package/.agents/docs/MIGRATION-STATUS.md +0 -35
  32. package/.agents/docs/MIGRATION-V8.md +0 -10
  33. package/.agents/docs/ROADMAP-V8.2.md +0 -78
  34. package/.agents/docs/V8-CERTIFICATION.md +0 -27
  35. package/.agents/skills/qk-access-policy/SKILL.md +0 -206
  36. package/.agents/skills/qk-access-policy/capability.yaml +0 -23
  37. package/.agents/skills/qk-access-policy/evals/scorecard.yaml +0 -36
  38. package/.agents/skills/qk-agent-observability/SKILL.md +0 -108
  39. package/.agents/skills/qk-agent-observability/capability.yaml +0 -29
  40. package/.agents/skills/qk-agent-observability/evals/scorecard.yaml +0 -29
  41. package/.agents/skills/qk-agent-observability/references/scorecard.yaml +0 -80
  42. package/.agents/skills/qk-ai-builder/SKILL.md +0 -254
  43. package/.agents/skills/qk-ai-builder/capability.yaml +0 -23
  44. package/.agents/skills/qk-ai-builder/evals/scorecard.yaml +0 -30
  45. package/.agents/skills/qk-api-consumer/SKILL.md +0 -256
  46. package/.agents/skills/qk-api-consumer/capability.yaml +0 -21
  47. package/.agents/skills/qk-api-consumer/evals/scorecard.yaml +0 -29
  48. package/.agents/skills/qk-api-lifecycle/SKILL.md +0 -251
  49. package/.agents/skills/qk-api-lifecycle/capability.yaml +0 -23
  50. package/.agents/skills/qk-api-lifecycle/evals/scorecard.yaml +0 -29
  51. package/.agents/skills/qk-bug-resolution/capability.yaml +0 -25
  52. package/.agents/skills/qk-code-review/capability.yaml +0 -23
  53. package/.agents/skills/qk-context-loader/SKILL.md +0 -198
  54. package/.agents/skills/qk-context-loader/capability.yaml +0 -23
  55. package/.agents/skills/qk-context-loader/evals/scorecard.yaml +0 -28
  56. package/.agents/skills/qk-data-engineer/SKILL.md +0 -253
  57. package/.agents/skills/qk-data-lifecycle/SKILL.md +0 -197
  58. package/.agents/skills/qk-data-lifecycle/capability.yaml +0 -23
  59. package/.agents/skills/qk-data-lifecycle/evals/scorecard.yaml +0 -29
  60. package/.agents/skills/qk-db-optimizer/SKILL.md +0 -210
  61. package/.agents/skills/qk-db-optimizer/capability.yaml +0 -22
  62. package/.agents/skills/qk-db-optimizer/evals/scorecard.yaml +0 -28
  63. package/.agents/skills/qk-design-system-engineering/SKILL.md +0 -193
  64. package/.agents/skills/qk-design-system-engineering/capability.yaml +0 -25
  65. package/.agents/skills/qk-design-system-engineering/evals/scorecard.yaml +0 -27
  66. package/.agents/skills/qk-devops-platform/SKILL.md +0 -198
  67. package/.agents/skills/qk-devops-platform/capability.yaml +0 -29
  68. package/.agents/skills/qk-devops-platform/evals/scorecard.yaml +0 -28
  69. package/.agents/skills/qk-docs/SKILL.md +0 -193
  70. package/.agents/skills/qk-docs/capability.yaml +0 -23
  71. package/.agents/skills/qk-docs/evals/scorecard.yaml +0 -27
  72. package/.agents/skills/qk-engineering-standard/SKILL.md +0 -89
  73. package/.agents/skills/qk-engineering-standard/capability.yaml +0 -23
  74. package/.agents/skills/qk-engineering-standard/evals/scorecard.yaml +0 -28
  75. package/.agents/skills/qk-engineering-standard/references/anti-patterns.md +0 -121
  76. package/.agents/skills/qk-engineering-standard/rules/backend.md +0 -122
  77. package/.agents/skills/qk-engineering-standard/rules/database.md +0 -3
  78. package/.agents/skills/qk-engineering-standard/rules/frontend.md +0 -152
  79. package/.agents/skills/qk-engineering-standard/rules/security.md +0 -3
  80. package/.agents/skills/qk-engineering-standard/rules/testing.md +0 -3
  81. package/.agents/skills/qk-fe-api-integration/SKILL.md +0 -704
  82. package/.agents/skills/qk-fe-api-integration/capability.yaml +0 -21
  83. package/.agents/skills/qk-fe-api-integration/evals/scorecard.yaml +0 -29
  84. package/.agents/skills/qk-feature-delivery/capability.yaml +0 -24
  85. package/.agents/skills/qk-frontend-architecture/SKILL.md +0 -127
  86. package/.agents/skills/qk-frontend-architecture/capability.yaml +0 -28
  87. package/.agents/skills/qk-frontend-architecture/evals/scorecard.yaml +0 -28
  88. package/.agents/skills/qk-help/SKILL.md +0 -107
  89. package/.agents/skills/qk-help/capability.yaml +0 -20
  90. package/.agents/skills/qk-help/evals/scorecard.yaml +0 -13
  91. package/.agents/skills/qk-orchestrator/capability.yaml +0 -22
  92. package/.agents/skills/qk-product-specification/SKILL.md +0 -187
  93. package/.agents/skills/qk-product-specification/capability.yaml +0 -27
  94. package/.agents/skills/qk-product-specification/evals/scorecard.yaml +0 -27
  95. package/.agents/skills/qk-production-release/SKILL.md +0 -188
  96. package/.agents/skills/qk-production-release/capability.yaml +0 -27
  97. package/.agents/skills/qk-production-release/evals/scorecard.yaml +0 -28
  98. package/.agents/skills/qk-project-audit/SKILL.md +0 -174
  99. package/.agents/skills/qk-project-bootstrap/SKILL.md +0 -372
  100. package/.agents/skills/qk-project-bootstrap/capability.yaml +0 -23
  101. package/.agents/skills/qk-project-bootstrap/evals/scorecard.yaml +0 -28
  102. package/.agents/skills/qk-project-health/SKILL.md +0 -202
  103. package/.agents/skills/qk-project-health/capability.yaml +0 -23
  104. package/.agents/skills/qk-project-health/evals/scorecard.yaml +0 -27
  105. package/.agents/skills/qk-project-memory/SKILL.md +0 -303
  106. package/.agents/skills/qk-project-memory/capability.yaml +0 -23
  107. package/.agents/skills/qk-project-memory/evals/scorecard.yaml +0 -27
  108. package/.agents/skills/qk-refactor/SKILL.md +0 -243
  109. package/.agents/skills/qk-refactor/capability.yaml +0 -26
  110. package/.agents/skills/qk-refactor/evals/scorecard.yaml +0 -27
  111. package/.agents/skills/qk-security-audit/SKILL.md +0 -280
  112. package/.agents/skills/qk-security-audit/capability.yaml +0 -29
  113. package/.agents/skills/qk-security-audit/evals/scorecard.yaml +0 -27
  114. package/.agents/skills/qk-system-evolution/SKILL.md +0 -625
  115. package/.agents/skills/qk-system-evolution/capability.yaml +0 -24
  116. package/.agents/skills/qk-system-evolution/evals/scorecard.yaml +0 -26
  117. package/.agents/skills/qk-test-engineering/SKILL.md +0 -215
  118. package/.agents/skills/qk-test-engineering/capability.yaml +0 -28
  119. package/.agents/skills/qk-test-engineering/evals/scorecard.yaml +0 -26
  120. package/.agents/skills/qk-ui-audit/SKILL.md +0 -175
  121. package/.agents/skills/qk-ui-audit/capability.yaml +0 -23
  122. package/.agents/skills/qk-ui-audit/evals/scorecard.yaml +0 -26
  123. package/.agents/skills/qk-ui-audit/references/anti-slop-checklist.md +0 -136
  124. package/.agents/skills/qk-ui-builder/SKILL.md +0 -521
  125. package/.agents/skills/qk-ui-builder/capability.yaml +0 -29
  126. package/.agents/skills/qk-ui-builder/evals/scorecard.yaml +0 -26
  127. package/.agents/skills/qk-ui-builder/references/anti-patterns.md +0 -295
  128. package/.agents/skills/qk-ui-builder/references/color.md +0 -115
  129. package/.agents/skills/qk-ui-builder/references/component-cookbook.md +0 -458
  130. package/.agents/skills/qk-ui-builder/references/copy.md +0 -250
  131. package/.agents/skills/qk-ui-builder/references/interaction-and-states.md +0 -115
  132. package/.agents/skills/qk-ui-builder/references/layout-and-space.md +0 -111
  133. package/.agents/skills/qk-ui-builder/references/macrostructures/01-bento-grid.md +0 -48
  134. package/.agents/skills/qk-ui-builder/references/macrostructures/02-long-document.md +0 -50
  135. package/.agents/skills/qk-ui-builder/references/macrostructures/03-marquee-hero.md +0 -51
  136. package/.agents/skills/qk-ui-builder/references/macrostructures/04-stat-led.md +0 -49
  137. package/.agents/skills/qk-ui-builder/references/macrostructures/05-workbench.md +0 -44
  138. package/.agents/skills/qk-ui-builder/references/macrostructures/06-conversational-faq.md +0 -50
  139. package/.agents/skills/qk-ui-builder/references/macrostructures/07-manifesto.md +0 -51
  140. package/.agents/skills/qk-ui-builder/references/macrostructures/08-photographic.md +0 -50
  141. package/.agents/skills/qk-ui-builder/references/macrostructures/09-quote-led.md +0 -50
  142. package/.agents/skills/qk-ui-builder/references/macrostructures/11-catalogue.md +0 -49
  143. package/.agents/skills/qk-ui-builder/references/macrostructures/12-letter.md +0 -49
  144. package/.agents/skills/qk-ui-builder/references/macrostructures/13-index-first.md +0 -49
  145. package/.agents/skills/qk-ui-builder/references/macrostructures/14-narrative-workflow.md +0 -48
  146. package/.agents/skills/qk-ui-builder/references/macrostructures/15-split-studio.md +0 -48
  147. package/.agents/skills/qk-ui-builder/references/macrostructures/16-feature-stack.md +0 -51
  148. package/.agents/skills/qk-ui-builder/references/macrostructures/17-type-specimen.md +0 -48
  149. package/.agents/skills/qk-ui-builder/references/macrostructures/18-portfolio-grid.md +0 -48
  150. package/.agents/skills/qk-ui-builder/references/macrostructures/19-map-diagram.md +0 -50
  151. package/.agents/skills/qk-ui-builder/references/macrostructures/20-ecosystem-index.md +0 -48
  152. package/.agents/skills/qk-ui-builder/references/macrostructures/21-component-playground.md +0 -45
  153. package/.agents/skills/qk-ui-builder/references/macrostructures.md +0 -38
  154. package/.agents/skills/qk-ui-builder/references/motion.md +0 -95
  155. package/.agents/skills/qk-ui-builder/references/responsive.md +0 -115
  156. package/.agents/skills/qk-ui-builder/references/slop-test.md +0 -135
  157. package/.agents/skills/qk-ui-builder/references/structure.md +0 -280
  158. package/.agents/skills/qk-ui-builder/references/themes/atmospheric.md +0 -53
  159. package/.agents/skills/qk-ui-builder/references/themes/carnival.md +0 -52
  160. package/.agents/skills/qk-ui-builder/references/themes/cobalt.md +0 -52
  161. package/.agents/skills/qk-ui-builder/references/themes/editorial.md +0 -52
  162. package/.agents/skills/qk-ui-builder/references/themes/garden.md +0 -52
  163. package/.agents/skills/qk-ui-builder/references/themes/hum.md +0 -52
  164. package/.agents/skills/qk-ui-builder/references/themes/lumen.md +0 -52
  165. package/.agents/skills/qk-ui-builder/references/themes/midnight.md +0 -52
  166. package/.agents/skills/qk-ui-builder/references/themes/modern-minimal.md +0 -52
  167. package/.agents/skills/qk-ui-builder/references/themes/playful.md +0 -52
  168. package/.agents/skills/qk-ui-builder/references/themes/specimen.md +0 -52
  169. package/.agents/skills/qk-ui-builder/references/themes/terminal.md +0 -52
  170. package/.agents/skills/qk-ui-builder/references/typography.md +0 -129
  171. package/.agents/skills/qk-ui-system-builder/SKILL.md +0 -183
  172. package/.agents/skills/qk-ui-system-builder/capability.yaml +0 -25
  173. package/.agents/skills/qk-ui-system-builder/evals/scorecard.yaml +0 -26
  174. package/.agents/skills/qk-upgrade/SKILL.md +0 -301
  175. package/.agents/skills/qk-upgrade/capability.yaml +0 -24
  176. package/.agents/skills/qk-upgrade/evals/scorecard.yaml +0 -26
  177. package/.agents/skills/qk-validation-gate/SKILL.md +0 -88
  178. package/.agents/skills/qk-validation-gate/capability.yaml +0 -23
  179. package/.agents/skills/qk-validation-gate/evals/scorecard.yaml +0 -26
  180. package/.agents/skills/qk-web-quality-gate/SKILL.md +0 -197
  181. package/.agents/skills/qk-web-quality-gate/capability.yaml +0 -24
  182. package/.agents/skills/qk-web-quality-gate/evals/scorecard.yaml +0 -26
  183. package/.agents/workflows/research.yml +0 -75
  184. package/.agents/workflows/skill-evolution.yml +0 -97
  185. package/tooling/fix-refactor.js +0 -8
@@ -1,5 +1,5 @@
1
1
  ---
2
- version: 9.2.0
2
+ version: 10.1.0
3
3
  description: "Agent behavior policies applied globally across all capabilities."
4
4
  domain: rules
5
5
  applies_to: all
@@ -11,7 +11,7 @@ applies_to: all
11
11
 
12
12
  ---
13
13
 
14
- ## R-G-01: Decision Before Action
14
+ ## R-G-01: Decision Before Action & Review Loop
15
15
 
16
16
  **MUST** create a plan before executing any task with complexity ≥ medium.
17
17
 
@@ -24,22 +24,31 @@ If medium/high: outline steps first
24
24
  ↓
25
25
  Execute step by step
26
26
  ↓
27
- Verify each step before next
27
+ Post-Implementation Self-Review (Requirements, Diff & Scope)
28
+ ↓
29
+ Verify with actual evidence
30
+ ↓
31
+ Conclude
28
32
  ```
29
33
 
30
- **Violation:** Starting to write code before understanding the full scope.
34
+ **Violation:** Starting to write code before understanding the full scope, or claiming completion without self-review.
31
35
 
32
36
  ---
33
37
 
34
- ## R-G-02: Evidence Before Conclusion
38
+ ## R-G-02: Evidence Before Conclusion & Causal Chain
35
39
 
36
- **MUST** have concrete evidence before stating a finding or applying a fix.
40
+ **MUST** establish concrete evidence and prove the causal link before stating a finding or applying a fix:
41
+
42
+ ```text
43
+ REQUEST ──► SCOPE ──► TARGETED INSPECTION ──► EVIDENCE ──► ROOT CAUSE ──► MINIMAL FIX ──► VERIFY ──► ANALYZE RESULT ──► STATUS
44
+ ```
37
45
 
38
- - Do NOT guess root cause without reading the relevant code.
39
- - Do NOT assume a bug is fixed without verification.
40
- - Do NOT report "done" without checking the output.
46
+ - Do NOT jump from Evidence directly to a fix without proving why that evidence points to the root cause.
47
+ - Do NOT guess root cause without inspecting the relevant code.
48
+ - Do NOT assume a bug is fixed without verification evidence.
49
+ - Do NOT report "done" without executing checks and analyzing results.
41
50
 
42
- **Minimum evidence:** File path + line number + quoted code.
51
+ **Minimum evidence:** File path + line number + quoted code + explicit explanation of why it causes the issue.
43
52
 
44
53
  ---
45
54
 
@@ -53,18 +62,17 @@ Verify each step before next
53
62
 
54
63
  ---
55
64
 
56
- ## R-G-04: Token Budget Discipline
65
+ ## R-G-04: Token Budget & Retrieval Discipline
57
66
 
58
- **MUST** respect the `token_budget` defined in each skill's frontmatter.
67
+ **MUST** respect the token budget and retrieval efficiency:
59
68
 
60
- - Read files in targeted chunks, never entire large files.
61
- - Use `grep_search` for pattern discovery, not full-file reads.
62
- - Stop reading when sufficient evidence is found (`stop_early: true`).
69
+ - Use targeted search tools available in the current environment for pattern discovery.
70
+ - Read only the minimum relevant sections and stop retrieval when sufficient evidence has been established.
63
71
  - Never read: `node_modules/`, `dist/`, `.git/`, binary files.
64
72
 
65
73
  ---
66
74
 
67
- ## R-G-05: Retrieval Path (Compact — v9.2)
75
+ ## R-G-05: Retrieval Path
68
76
 
69
77
  When starting a task, follow this sequence:
70
78
 
@@ -79,9 +87,8 @@ When starting a task, follow this sequence:
79
87
  ```
80
88
 
81
89
  **Do NOT:**
82
- - Read `registry/skills-index.yml` to route — use the inline routing table in `.agents/AGENTS.md`
83
- - Load all skills at once
84
- - Scan entire repository before starting
90
+ - Load all skills at once.
91
+ - Scan entire repository before starting.
85
92
 
86
93
  ---
87
94
 
@@ -111,7 +118,7 @@ Never silently terminate. Always report exit code and reason.
111
118
 
112
119
  ## R-G-08: No Silent Errors
113
120
 
114
- **NEVER** use `?.`, `!`, `try/catch {}` (empty catch), or type casting to suppress errors.
121
+ **NEVER** use `!` (non-null assertion), empty `try/catch {}` (suppressing errors silently), or blind type casting (`as any`) to hide errors. Optional chaining (`?.`) is allowed and recommended for safe navigation of nullable/optional properties.
115
122
 
116
123
  Fix root cause. If root cause is unclear → report as `BLOCKED` with evidence.
117
124
 
@@ -130,9 +137,9 @@ Deprecated skills **MUST NOT** be selected. If a user asks for a deprecated skil
130
137
  Agent **MUST NOT** execute when selection confidence < threshold.
131
138
 
132
139
  Agent **SHOULD**:
133
- 1. Ask clarification
134
- 2. Present top 2-3 candidate skills with brief descriptions
135
- 3. Explain what information is missing
140
+ 1. Ask clarification.
141
+ 2. Present top 2-3 candidate skills with brief descriptions.
142
+ 3. Explain what information is missing.
136
143
 
137
144
  ---
138
145
 
@@ -140,11 +147,8 @@ Agent **SHOULD**:
140
147
 
141
148
  Every SKILL.md `description` field **MUST** satisfy both:
142
149
 
143
- **(a) What it does** — concrete action the skill performs
144
- **(b) When to use** — trigger context, keywords, situations
145
-
146
- **Bad:** `"Xử lý dữ liệu."`
147
- **Good:** `"Thiết kế và implement API endpoint mới (REST/GraphQL/tRPC). Dùng skill này khi user nhắc đến: viết api, tạo endpoint, thiết kế api, build api, route handler, controller — kể cả khi chỉ hỏi về request/response schema."`
150
+ **(a) What it does** — concrete action the skill performs
151
+ **(b) When to use** — trigger context, keywords, situations
148
152
 
149
153
  Description phải đủ mạnh để AI **không under-trigger** (bỏ qua skill khi lẽ ra nên dùng).
150
154
 
@@ -160,3 +164,205 @@ Nếu gần chạm 500 dòng:
160
164
  - Layer 1 (frontmatter) luôn trong context
161
165
  - Layer 2 (SKILL.md body) nạp khi skill active
162
166
  - Layer 3 (references/, scripts/, assets/) nạp on-demand
167
+
168
+ ---
169
+
170
+ ## R-G-13: Laser Focus & Anti-Sprawl
171
+
172
+ Agent **BẮT BUỘC** khóa chặt phạm vi thực thi theo 3 nguyên tắc thép:
173
+
174
+ ### 13.1. Scope Lock & No Unrelated Changes
175
+ - **Chỉ giải quyết đúng yêu cầu hiện tại:** Không tự mở rộng phạm vi sang refactor, bug fixing, optimization, redesign hoặc cleanup không liên quan.
176
+ - **Cấm sửa lan man:** Không sửa các file không liên quan chỉ vì phát hiện chúng "có thể cải thiện".
177
+ - **Ghi nhận thay vì tự tiện:** Nếu phát hiện vấn đề ngoài phạm vi, **CHỈ GHI NHẬN VÀ BÁO CÁO** trong phần ghi chú, tuyệt đối không tự ý sửa.
178
+ - **Câu hỏi phán xét:** Mọi thay đổi phải trả lời được câu hỏi: *"Thay đổi này có cần thiết trực tiếp cho yêu cầu hiện tại không?"*. Nếu câu trả lời là "KHÔNG" ➔ **TUYỆT ĐỐI KHÔNG THỰC HIỆN**.
179
+
180
+ ### 13.2. File Creation Control (Kiểm Soát Sinh File)
181
+ - **Không tạo file chỉ để làm kiến trúc trông đẹp hơn.**
182
+ - Trước khi tạo file mới, **BẮT BUỘC** kiểm tra repository để xác định:
183
+ 1. Có file/component/service/hook hiện tại nào có thể tái sử dụng được không?
184
+ 2. Có pattern tương tự trong project hay không?
185
+ 3. File mới có thực sự cần thiết cho tính năng hay không?
186
+ - **Ưu tiên chỉnh sửa và tái sử dụng cấu trúc hiện có:** Chỉ tạo file mới khi có lý do kỹ thuật rõ ràng và file đó có trách nhiệm riêng biệt (Single Responsibility). Cấm tạo các abstraction trung gian chỉ để "đúng pattern".
187
+
188
+ ### 13.3. Repository Inspection Rule (Quét Có Mục Đích)
189
+ - Trước khi triển khai, chỉ quét những file và thư mục **có khả năng liên quan trực tiếp**.
190
+ - Tuyệt đối **KHÔNG**:
191
+ - Quét và phân tích toàn bộ repository một cách không cần thiết.
192
+ - Đọc hàng loạt file không liên quan.
193
+ - Biến việc "khảo sát codebase" thành một nhiệm vụ cleanup toàn dự án.
194
+
195
+ ---
196
+
197
+ ## R-G-14: Zero-Faked Pass & Root-Cause Verification
198
+
199
+ Agent MUST treat **PASS as a verified conclusion, never as a target**.
200
+
201
+ ### 14.1. Root-Cause Gate
202
+
203
+ Before applying a fix, Agent MUST establish:
204
+ 1. What is the observed problem?
205
+ 2. Where does it occur?
206
+ 3. What code path causes it?
207
+ 4. What is the root cause?
208
+ 5. Why will the proposed change remove the root cause?
209
+
210
+ Do NOT apply speculative fixes.
211
+
212
+ If root cause cannot be established with sufficient evidence:
213
+ ```text
214
+ BLOCKED
215
+ Reason: Root cause cannot be established from available evidence.
216
+ ```
217
+
218
+ ### 14.2. Minimal Correct Fix
219
+
220
+ The fix MUST:
221
+ - Address the identified root cause.
222
+ - Be the smallest change that correctly resolves the problem.
223
+ - Preserve unrelated behavior.
224
+ - Avoid introducing unnecessary abstractions or files.
225
+ - Avoid workaround code whose only purpose is to make verification pass.
226
+
227
+ ### 14.3. Post-Implementation Review Gate — REVIEW TRƯỚC KHI PASS
228
+
229
+ Agent **MUST NOT** declare a task complete immediately after implementation.
230
+
231
+ Sau khi hoàn thành thay đổi, Agent **BẮT BUỘC** thực hiện một vòng self-review độc lập trước khi chạy verification và kết luận:
232
+
233
+ ```text
234
+ REQUEST ──► PLAN ──► TARGETED INSPECTION ──► EVIDENCE ──► ROOT CAUSE ──► IMPLEMENT
235
+ │
236
+ ▼
237
+ 🔍 POST-IMPLEMENTATION REVIEW
238
+ ├── 1. Requirement Review: Đã đáp ứng đúng yêu cầu ban đầu? Có thiếu edge case nào không?
239
+ ├── 2. Implementation Review: Code có giải quyết triệt để root cause? Có logic/file thừa không?
240
+ ├── 3. Scope Review (Diff Check): Những file nào đã sửa? Có accidental hay unrelated changes không?
241
+ ├── 4. Quality Review: Có vi phạm as any, @ts-ignore, silent catch, hay dirty workaround không?
242
+ └── 5. Verification Review: Đã xác định đúng lệnh test/build thực tế cần chạy chưa?
243
+ │
244
+ ├── Nếu Review phát hiện lỗi ──► STOP ──► RE-ANALYZE ──► MINIMAL FIX ──► REVIEW AGAIN
245
+ │
246
+ ▼
247
+ 14.4. VERIFICATION GATE (Chạy lệnh thực tế) ──► 14.5. FAILURE RE-ANALYSIS (nếu fail)
248
+ │
249
+ ▼
250
+ 14.6. ANTI-FAKE-PASS ──► 14.7. EVIDENCE-BASED STATUS ──► 14.8. TRUTH-FIRST REPORTING
251
+ ```
252
+
253
+ #### Final Gate Condition:
254
+ Chỉ được kết luận `SUCCESS` khi:
255
+ - Requirement đã được đối chiếu đầy đủ.
256
+ - Implementation đã được self-review độc lập.
257
+ - Scope / Diff đã được kiểm tra (0 unrelated changes).
258
+ - Root cause đã được xử lý đúng.
259
+ - Verification thực tế đạt yêu cầu (có output lệnh thực tế).
260
+ - Không có bất kỳ workaround nào để ép PASS.
261
+
262
+ > **Implementation complete ≠ Task complete.**
263
+ > **Task complete = Implementation + Review + Verification + Evidence.**
264
+
265
+ ### 14.4. Verification Gate
266
+
267
+ After applying the fix and completing self-review, Agent MUST run the most relevant available verification:
268
+ - Unit tests
269
+ - Integration tests
270
+ - Type-check
271
+ - Lint
272
+ - Build
273
+ - Relevant runtime/manual verification
274
+
275
+ Only verification actually executed may be reported as evidence.
276
+
277
+ ### 14.5. Failure Re-Analysis
278
+
279
+ If verification FAILS:
280
+ ```text
281
+ FAIL
282
+ ↓
283
+ STOP
284
+ ↓
285
+ Read actual failure
286
+ ↓
287
+ Re-analyze root cause
288
+ ↓
289
+ Determine whether previous diagnosis was incomplete/wrong
290
+ ↓
291
+ Apply corrected minimal fix
292
+ ↓
293
+ Review again
294
+ ↓
295
+ Verify again
296
+ ```
297
+ Do NOT repeatedly modify code blindly until the check becomes green.
298
+
299
+ ### 14.6. Anti-Fake-Pass
300
+
301
+ Agent MUST NOT make a verification pass by:
302
+ - Adding `as any`
303
+ - Adding `@ts-ignore`
304
+ - Adding `@ts-expect-error` to suppress a newly introduced error
305
+ - Disabling lint/type-check/test rules
306
+ - Skipping or deleting failing tests
307
+ - Weakening assertions without justification
308
+ - Hardcoding fake outputs
309
+ - Returning fake/mock data in production code
310
+ - Swallowing exceptions (`catch (e) {}` rỗng)
311
+ - Changing expected results merely to match incorrect behavior
312
+ - Modifying configuration solely to hide failures
313
+
314
+ ### 14.7. Evidence-Based Status
315
+
316
+ Agent MUST distinguish:
317
+
318
+ | Status | Requirement |
319
+ |---|---|
320
+ | `SUCCESS` | Correct fix + self-reviewed + relevant verification passed |
321
+ | `BLOCKED` | Root cause/precondition cannot be established or required verification cannot proceed |
322
+ | `FAILED` | Correct execution attempted but task could not be completed |
323
+ | `PARTIAL` | Some scoped work completed, but required verification or implementation remains incomplete |
324
+
325
+ Never convert `BLOCKED`, `FAILED`, or `PARTIAL` into `SUCCESS` merely because the code was modified.
326
+
327
+ ### 14.8. Truth-First Reporting
328
+
329
+ Never claim:
330
+ - "100% fixed"
331
+ - "All tests pass"
332
+ - "Build passes"
333
+ - "No issues"
334
+ - "Verified"
335
+
336
+ unless the corresponding verification was actually executed and passed.
337
+
338
+ If verification cannot be executed:
339
+ ```text
340
+ Status: NOT VERIFIED
341
+ Reason: <concrete reason>
342
+ ```
343
+ Do not infer PASS from code inspection alone.
344
+
345
+ ---
346
+
347
+ ## R-G-15: Prompt Interpretation & Control Plane Gate (Risk Gate, Change Budget, Scope Expansion & Evidence Gate)
348
+
349
+ **MUST** translate raw or concise user requests into an explicit, reviewable **Compiled Execution Prompt**, expose **Prompt Delta**, and enforce 4 control gates before and during execution.
350
+
351
+ ```text
352
+ RAW REQUEST ──► COMPILE & DELTA ──► RISK & BUDGET GATE ──► DECIDE MODE (AUTO/CONFIRM/ASK) ──► EXECUTE ──► SCOPE EXPANSION GATE? ──► EVIDENCE GATE ──► REPORT
353
+ ```
354
+
355
+ ### 15.1. Core Maxim
356
+ > `AI MUST NEVER INCREASE THE USER'S INTENDED SCOPE SILENTLY.`
357
+ > *(The AI may increase implementation detail, but must never silently increase business scope, behavioral scope, architectural scope, security scope, data scope, or change budget).*
358
+
359
+ ### 15.2. Mandatory Gates
360
+ 1. **Risk Gate (`Complexity ≠ Risk`):** Đánh giá độc lập Complexity (`L0–L4`) và Risk (`R0–R4`). Nếu `Risk >= R2` hoặc `Complexity >= L3` hoặc đụng đến Auth/DB/Production → BẮT BUỘC chọn chế độ `CONFIRM`.
361
+ 2. **Change Budget Gate:** Khóa giới hạn thay đổi (Kỳ vọng 1–3 files, tối đa 5 files; 0 new dependencies; không đổi API/DB trừ khi được yêu cầu).
362
+ 3. **Scope Expansion Gate:** Trong khi code, nếu phát hiện phạm vi thực tế vượt Compiled Scope → **STOP EXPANSION NGAY LẬP TỨC**, báo cáo nguyên nhân và recompile để chờ người dùng duyệt (`CONFIRM`).
363
+ 4. **Evidence Gate:** `CLAIM LEVEL <= EVIDENCE LEVEL`. Không được khẳng định pass khi chỉ đọc code. Phải phân biệt rõ `VERIFIED`, `PARTIALLY VERIFIED`, và `UNVERIFIED`.
364
+
365
+ - **Reference:** Detailed policies in [PROMPT_RULES.md](./PROMPT_RULES.md) and [.agents/rules/prompt-compiler.md](.agents/rules/prompt-compiler.md).
366
+
367
+
368
+
@@ -0,0 +1,170 @@
1
+ ---
2
+ version: 11.1.0
3
+ description: "Quy tắc Prompt Compiler v11.1 Control Plane: Cổng kiểm soát hành vi, Risk Gate R0-R4, Change Budget, Scope Expansion Gate, Evidence Gate và Prompt Delta."
4
+ domain: rules
5
+ applies_to: all
6
+ ---
7
+
8
+ # Prompt Compiler Rules v11.1 — Control Plane & Behavioral Gate
9
+
10
+ > **Câu hỏi domain này trả lời:** *Làm thế nào để kiểm soát hành vi của AI trước và trong khi code, ngăn chặn bành trướng phạm vi âm thầm, giới hạn ngân sách thay đổi và khóa mức độ khẳng định theo bằng chứng thực tế?*
11
+
12
+ ---
13
+
14
+ ## 1. Nguyên Tắc Cốt Lõi & Khẩu Hiệu Kiến Trúc (Core Maxims)
15
+
16
+ > 1. `AI MUST NEVER INCREASE THE USER'S INTENDED SCOPE SILENTLY.`
17
+ > *(AI tuyệt đối không bao giờ được âm thầm bành trướng phạm vi ý định của người dùng).*
18
+ >
19
+ > 2. `The AI may increase implementation detail, but must never silently increase business scope, behavioral scope, architectural scope, security scope, data scope, or change budget.`
20
+ > *(AI có thể đào sâu chi tiết triển khai kỹ thuật, nhưng cấm âm thầm tăng phạm vi nghiệp vụ, hành vi, kiến trúc, bảo mật, dữ liệu hoặc ngân sách thay đổi).*
21
+
22
+ ---
23
+
24
+ ## 2. Thứ Bậc Ngữ Cảnh Hóa Biên Dịch (Context-Aware Compilation Hierarchy)
25
+
26
+ ```text
27
+ SYSTEM / PLATFORM RULES
28
+ ↓
29
+ PROJECT RULES
30
+ ↓
31
+ GLOBAL RULES
32
+ ↓
33
+ RELEVANT SKILL
34
+ ↓
35
+ PROJECT CONTEXT / DEV_PROFILE.md
36
+ ↓
37
+ EXISTING ARCHITECTURE & CODE
38
+ ↓
39
+ USER REQUIREMENT ◄── [NGUỒN CHÍNH XÁC ĐỊNH MỤC TIÊU CỐT LÕI (WHAT)]
40
+ ↓
41
+ AI INTERPRETATION
42
+ ↓
43
+ EXECUTION PLAN ◄── [QUY CHUẨN KỸ THUẬT & RANH GIỚI BẢO VỆ (HOW & BOUNDARIES)]
44
+ ```
45
+
46
+ - **User Requirement:** Là nguồn sự thật tối thượng để xác định **Mục tiêu cần làm gì (WHAT)**.
47
+ - **Rules, Skills & Codebase:** Đóng vai trò là luật lệ, ranh giới và tiêu chuẩn kỹ thuật để quy định **Cách AI được phép thực hiện an toàn (HOW & BOUNDARIES)**.
48
+
49
+ ---
50
+
51
+ ## 3. Cổng Đánh Giá Rủi Ro Độc Lập (Risk Gate: Complexity ≠ Risk)
52
+
53
+ Một thay đổi 1 dòng trong file cấu hình Production (`L1`) có thể gây sập hệ thống (`R4`). Hai trục này phải được đánh giá riêng biệt:
54
+
55
+ ### Trục Phức Tạp (Complexity)
56
+ - `L0 — Trivial`: Sửa typo, format markdown.
57
+ - `L1 — Simple`: Sửa 1 hàm nhỏ, tinh chỉnh CSS cục bộ 1 component.
58
+ - `L2 — Normal`: Bug logic thông thường, thêm 1 endpoint/hook trong module.
59
+ - `L3 — Complex`: Tính năng liên tầng (FE + BE), tái cấu trúc module.
60
+ - `L4 — High Architecture`: Thiết kế lại flow hoặc kiến trúc hệ thống.
61
+
62
+ ### Trục Rủi Ro (Risk Levels)
63
+ - `R0 — Safe`: Thao tác chỉ đọc (Read-only), audit, tài liệu.
64
+ - `R1 — Low`: Thay đổi nhỏ, local UI, dễ rollback, không side-effect.
65
+ - `R2 — Medium`: Logic nghiệp vụ, hàm dùng chung, có nguy cơ hồi quy (regression).
66
+ - `R3 — High`: Sửa đổi liên tầng, API contract, database migration, CI/CD config.
67
+ - `R4 — Critical`: Destructive operation (DROP, TRUNCATE, DELETE), bảo mật/auth, production data.
68
+
69
+ ### Ma Trận Quyết Định Chế Độ (Mode Matrix)
70
+ ```text
71
+ IF Complexity >= L3 ──► Minimum CONFIRM
72
+ IF Risk >= R2 ──► Minimum CONFIRM
73
+ IF Risk >= R3 ──► CONFIRM + Explicit Risk Report
74
+ IF destructive / auth / production data ──► BẮT BUỘC CONFIRM (Chờ duyệt [Proceed])
75
+ IF thiếu thông tin / intent mơ hồ ──► BẮT BUỘC ASK (Hỏi lại, không đoán)
76
+ ```
77
+
78
+ ---
79
+
80
+ ## 4. Ngân Sách Thay Đổi (Change Budget Gate)
81
+
82
+ Khóa chặt quy mô can thiệp cho mỗi task:
83
+ - **Files Budget:** Dự kiến 1–3 files; Tối đa 5 files. Vượt quá 5 files = Vi phạm budget.
84
+ - **Dependencies Budget:** Mặc định = 0 new dependencies. Cấm tự ý `npm install` thêm package nếu chưa hỏi.
85
+ - **API Contract:** Không thay đổi (trừ khi task yêu cầu).
86
+ - **Database Schema:** Không thay đổi (trừ khi task yêu cầu).
87
+ - **Architecture:** Không tự tiện rewrite.
88
+
89
+ ---
90
+
91
+ ## 5. Cổng Chặn Bành Trướng Phạm Vi (Scope Expansion Gate)
92
+
93
+ Khi đang thực hiện (in-flight execution), nếu AI phát hiện lỗi nằm xuyên tầng hoặc cần sửa ngoài phạm vi đã compile:
94
+ ```text
95
+ STOP EXPANSION NGAY LẬP TỨC
96
+ ↓
97
+ BÁO CÁO PHÁT SINH PHẠM VI (SCOPE EXPANSION REPORT):
98
+ - Scope ban đầu đã duyệt
99
+ - Phụ thuộc mới phát hiện
100
+ - Lý do kỹ thuật vì sao bắt buộc phải mở rộng
101
+ - Files bị ảnh hưởng & Mức tăng rủi ro (Risk escalation)
102
+ ↓
103
+ RECOMPILE PROMPT & PROMPT DELTA MỚI
104
+ ↓
105
+ CHỜ NGƯỜI DÙNG PHÊ DUYỆT (CONFIRM) MỚI ĐƯỢC LÀM TIẾP
106
+ ```
107
+
108
+ ---
109
+
110
+ ## 6. Cổng Bằng Chứng Khẳng Định (Evidence Gate)
111
+
112
+ ```text
113
+ NGUYÊN TẮC:
114
+ CLAIM LEVEL <= EVIDENCE LEVEL
115
+ (Mức độ khẳng định của AI không được vượt quá mức độ bằng chứng thực tế thu thập được)
116
+ ```
117
+
118
+ Phân cấp 3 trạng thái nghiệm thu:
119
+ 1. **`VERIFIED`:** Đã chạy test/build thực tế trong terminal và PASS.
120
+ 2. **`PARTIALLY VERIFIED`:** Static analysis / typecheck / lint PASS, chưa test luồng integration/browser thật.
121
+ 3. **`UNVERIFIED`:** Chưa chạy test, chỉ review code tĩnh. **CẤM GHI PASS**, bắt buộc ghi: *"Trạng thái: NOT VERIFIED — Đã sửa logic tĩnh. Cần người dùng kiểm thử thủ công."*
122
+
123
+ ---
124
+
125
+ ## 7. Khung Hiển Thị Mặc Định (Default UI Block với Prompt Delta & Budget)
126
+
127
+ Khi nhận câu lệnh, AI bắt buộc render cấu trúc sau trước khi code:
128
+
129
+ ````markdown
130
+ ## 🧠 1. Tôi hiểu yêu cầu
131
+ [Tóm tắt 1-2 câu về mục tiêu thực sự bạn muốn đạt được]
132
+
133
+ ## 📝 2. Prompt tôi sẽ dùng (Compiled Execution Prompt)
134
+ ```text
135
+ Role: <vai trò chuyên trách trong 14 Roles>
136
+ Objective: <mục tiêu đo lường được, định nghĩa rõ "DONE = ?">
137
+ Context: <stack & module liên quan từ DEV_PROFILE.md và codebase>
138
+ Source of Truth: <thứ tự ưu tiên nguồn dữ liệu>
139
+ Scope:
140
+ - IN-SCOPE: <file/hàm được phép sửa>
141
+ - OUT-OF-SCOPE: <vùng cấm tuyệt đối>
142
+ Constraints: Minimal Safe Change, YAGNI, không phá vỡ API/DB hiện có, zero fake pass
143
+ Process: <các bước logic tối giản>
144
+ Acceptance Criteria:
145
+ - [ ] <Điều kiện kiểm chứng 1>
146
+ - [ ] <Điều kiện kiểm chứng 2>
147
+ ```
148
+
149
+ ## 🔍 3. Prompt Delta (Tôi đã diễn giải thêm)
150
+
151
+ ### User đã yêu cầu:
152
+ - [Nguyên văn câu lệnh bạn đưa]
153
+
154
+ ### AI suy luận từ context:
155
+ - [Những điểm kỹ thuật AI bổ sung dựa trên mã nguồn thực tế]
156
+
157
+ ### AI KHÔNG tự giả định:
158
+ - [Những ranh giới AI tự khóa lại: không rewrite, không đổi DB, không sửa lan man]
159
+
160
+ ## 📊 4. Đánh Giá Rủi Ro & Ngân Sách Thay Đổi (Risk & Budget)
161
+ - **Độ phức tạp / Rủi ro:** `L[0-4]` / `R[0-4]` — [Đánh giá ngắn]
162
+ - **Ngân sách file (Change Budget):** Tối đa [N] files (`path/to/file1`)
163
+ - **Dependencies mới:** 0 package
164
+
165
+ ## 📋 5. Các bước thực hiện
166
+ 1. [Khảo sát] → 2. [Thực thi tối thiểu] → 3. [Xác minh theo Evidence Gate]
167
+
168
+ ## ⚡ 6. Execution Mode
169
+ **[ AUTO | CONFIRM | ASK ]** — [Lý do lựa chọn mode dựa trên ma trận Risk & Complexity]
170
+ ````