@anhlp/alp-core 0.0.0-beta.2 → 0.0.1-beta.10

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 (158) hide show
  1. package/dist/backup.js +106 -4
  2. package/dist/bridges.d.ts +26 -0
  3. package/dist/bridges.js +96 -0
  4. package/dist/gate-ledger.d.ts +30 -0
  5. package/dist/gate-ledger.js +99 -0
  6. package/dist/index.d.ts +1 -0
  7. package/dist/index.js +2 -0
  8. package/dist/library-edit.d.ts +57 -5
  9. package/dist/library-edit.js +216 -11
  10. package/dist/library.d.ts +14 -1
  11. package/dist/library.js +73 -5
  12. package/dist/migrations.js +1 -1
  13. package/dist/models.d.ts +74 -0
  14. package/dist/models.js +67 -1
  15. package/dist/packaged.d.ts +122 -0
  16. package/dist/packaged.js +125 -0
  17. package/dist/packs.d.ts +57 -0
  18. package/dist/packs.js +247 -0
  19. package/dist/permissions.d.ts +3 -2
  20. package/dist/permissions.js +6 -3
  21. package/dist/profiles.js +6 -6
  22. package/dist/providers.d.ts +4 -5
  23. package/dist/providers.js +26 -5
  24. package/dist/skill-validate.d.ts +85 -0
  25. package/dist/skill-validate.js +298 -0
  26. package/dist/task-rows.d.ts +5 -0
  27. package/dist/task-rows.js +1 -1
  28. package/dist/tasks.d.ts +23 -4
  29. package/dist/tasks.js +103 -9
  30. package/dist/types.d.ts +3 -0
  31. package/dist/upgrade.d.ts +10 -0
  32. package/dist/upgrade.js +112 -6
  33. package/dist/user-settings.d.ts +2 -0
  34. package/dist/user-settings.js +40 -1
  35. package/dist/user-worktree.d.ts +29 -0
  36. package/dist/user-worktree.js +242 -0
  37. package/dist/validation.d.ts +1 -0
  38. package/dist/validation.js +35 -13
  39. package/package.json +34 -2
  40. package/src/backup.js +106 -5
  41. package/src/bridges.js +113 -0
  42. package/src/gate-ledger.js +125 -0
  43. package/src/index.js +1 -0
  44. package/src/library-edit.js +227 -12
  45. package/src/library.js +96 -6
  46. package/src/migrations.js +1 -1
  47. package/src/models.js +87 -1
  48. package/src/packaged.js +207 -0
  49. package/src/packs.js +246 -0
  50. package/src/permissions.d.ts +3 -2
  51. package/src/permissions.js +13 -3
  52. package/src/profiles.js +7 -7
  53. package/src/providers.js +23 -7
  54. package/src/resolver.js +1 -1
  55. package/src/skill-validate.js +287 -0
  56. package/src/task-rows.js +1 -1
  57. package/src/tasks.d.ts +23 -4
  58. package/src/tasks.js +137 -10
  59. package/src/types.d.ts +3 -0
  60. package/src/upgrade.js +54 -6
  61. package/src/user-settings.d.ts +2 -0
  62. package/src/user-settings.js +51 -1
  63. package/src/user-worktree.js +259 -0
  64. package/src/validation.d.ts +1 -0
  65. package/src/validation.js +43 -14
  66. package/templates/ALP.md +52 -52
  67. package/templates/agents/lead/AGENT.md +77 -74
  68. package/templates/agents/main/AGENT.md +153 -141
  69. package/templates/agents/oracle/AGENT.md +38 -37
  70. package/templates/agents/peer/AGENT.md +56 -52
  71. package/templates/agents/reviewer/AGENT.md +63 -65
  72. package/templates/agents/supervisor/AGENT.md +63 -63
  73. package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
  74. package/templates/packs/architecture/agents/architect/agent.json +5 -0
  75. package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
  76. package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
  77. package/templates/packs/architecture/pack.json +7 -0
  78. package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
  79. package/templates/packs/architecture/teams/blueprint/team.json +19 -0
  80. package/templates/packs/backend/pack.json +6 -0
  81. package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
  82. package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
  83. package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
  84. package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
  85. package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
  86. package/templates/packs/backend/skills/databases/SKILL.md +103 -0
  87. package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
  88. package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
  89. package/templates/packs/design/pack.json +6 -0
  90. package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
  91. package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
  92. package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
  93. package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
  94. package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
  95. package/templates/packs/frontend/pack.json +6 -0
  96. package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
  97. package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
  98. package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
  99. package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
  100. package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
  101. package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
  102. package/templates/packs/integration/pack.json +6 -0
  103. package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
  104. package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
  105. package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
  106. package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
  107. package/templates/packs/operations/pack.json +6 -0
  108. package/templates/packs/operations/skills/devops/SKILL.md +85 -0
  109. package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
  110. package/templates/packs/operations/skills/devops/references/containers.md +85 -0
  111. package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
  112. package/templates/packs/operations/skills/devops/references/observability.md +86 -0
  113. package/templates/packs/quality/pack.json +6 -0
  114. package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
  115. package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
  116. package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
  117. package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
  118. package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
  119. package/templates/role-skills.json +4 -4
  120. package/templates/skills/architecture-docs/SKILL.md +81 -0
  121. package/templates/skills/architecture-docs/references/adr.md +62 -0
  122. package/templates/skills/architecture-docs/references/diagrams.md +60 -0
  123. package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
  124. package/templates/skills/bug-loop/SKILL.md +41 -40
  125. package/templates/skills/bug-loop/references/test-proof.md +21 -19
  126. package/templates/skills/compact/SKILL.md +34 -0
  127. package/templates/skills/curate/SKILL.md +36 -0
  128. package/templates/skills/feature-architecture/SKILL.md +90 -0
  129. package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
  130. package/templates/skills/feature-architecture/references/feature-design.md +69 -0
  131. package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
  132. package/templates/skills/goal-griller/SKILL.md +27 -27
  133. package/templates/skills/prompt-leverage/SKILL.md +29 -27
  134. package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
  135. package/templates/skills/release-readiness/SKILL.md +83 -0
  136. package/templates/skills/release-readiness/references/checklist.md +40 -0
  137. package/templates/skills/release-readiness/references/verdict-template.md +53 -0
  138. package/templates/skills/safe-refactor/SKILL.md +84 -0
  139. package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
  140. package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
  141. package/templates/skills/security-review/SKILL.md +87 -0
  142. package/templates/skills/security-review/references/checklist.md +74 -0
  143. package/templates/skills/security-review/references/severity.md +61 -0
  144. package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
  145. package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
  146. package/templates/skills/skill-authoring/SKILL.md +84 -0
  147. package/templates/skills/skill-authoring/references/evaluation.md +45 -0
  148. package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
  149. package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
  150. package/templates/skills/smart-commits/SKILL.md +37 -36
  151. package/templates/skills/test-strategy/SKILL.md +83 -0
  152. package/templates/skills/test-strategy/references/contract-tests.md +46 -0
  153. package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
  154. package/templates/skills/xia/SKILL.md +40 -38
  155. package/templates/teams/cafe/HOUSE_RULES.md +1 -1
  156. package/templates/teams/cafe/team.json +1 -1
  157. package/templates/teams/pho/HOUSE_RULES.md +1 -1
  158. package/templates/teams/pho/team.json +1 -1
@@ -0,0 +1,60 @@
1
+ # Sơ đồ
2
+
3
+ Đọc khi thêm hoặc cập nhật một sơ đồ Mermaid trong tài liệu kiến trúc.
4
+
5
+ ## Quy tắc
6
+ - Mỗi node ứng với một module, package, service hay đường dẫn thật; đặt đường dẫn vào
7
+ nhãn hoặc vào một ghi chú bên dưới sơ đồ.
8
+ - Mỗi mũi nối ứng với một import, lời gọi, message, route hay mục config mà bạn dẫn nguồn được.
9
+ - Nhiều nhất khoảng 12 node; hãy tách theo ranh giới chứ đừng thu nhỏ nhãn.
10
+ - Một sơ đồ, một câu hỏi: cấu trúc, đường đi của một request, hoặc cách triển khai. Không gộp
11
+ cả ba.
12
+ - Ghi nhãn mũi nối bằng protocol hoặc động từ khi điều đó không hiển nhiên.
13
+ - Không tô kiểu, màu hay icon trừ khi tài liệu của project đã dùng chúng.
14
+ - Sinh lại từ code khi ranh giới đổi; xoá sơ đồ không ai bảo trì.
15
+ - Các cạnh chưa kiểm chứng dùng mũi nối nét đứt kèm ghi chú "Unverified".
16
+
17
+ ## Flowchart: phụ thuộc giữa các module
18
+ ```mermaid
19
+ flowchart LR
20
+ cli["cli (packages/cli)"] --> core["core (packages/core)"]
21
+ daemon["daemon (packages/daemon)"] --> core
22
+ daemon --> runtime["runtime (packages/runtime)"]
23
+ runtime -.-> core
24
+ ```
25
+ Ghi chú: cạnh nét đứt đánh dấu một import chỉ thấy trong test (Unverified với code runtime).
26
+
27
+ ## Sequence: đường đi của một request
28
+ ```mermaid
29
+ sequenceDiagram
30
+ participant C as Client
31
+ participant R as Router (src/routes/orders.ts)
32
+ participant S as OrderService (src/orders/service.ts)
33
+ participant D as DB
34
+ C->>R: POST /orders
35
+ R->>S: create(input)
36
+ S->>D: insert order
37
+ D-->>S: id
38
+ S-->>R: Order
39
+ R-->>C: 201 Created
40
+ ```
41
+
42
+ ## Góc nhìn container (kiểu C4, vẽ bằng flowchart)
43
+ ```mermaid
44
+ flowchart TB
45
+ user([User])
46
+ subgraph system [Shop system]
47
+ web["web app (apps/web)"]
48
+ api["api (apps/api)"]
49
+ db[("Postgres, from docker-compose.yml")]
50
+ end
51
+ pay["Payment provider (external)"]
52
+ user --> web --> api --> db
53
+ api -->|HTTPS| pay
54
+ ```
55
+
56
+ ## Kiểm một sơ đồ
57
+ - Với mỗi node, xác nhận đường dẫn tồn tại.
58
+ - Với mỗi cạnh, tìm dòng import, lời gọi hay config; dẫn nó trong phần chữ xung quanh.
59
+ - Render bằng công cụ tài liệu của project nếu có; nếu không thì soi cú pháp bằng mắt dựa trên
60
+ các ví dụ này và giữ sơ đồ đơn giản.
@@ -0,0 +1,49 @@
1
+ # Quy tắc về bằng chứng
2
+
3
+ Đọc khi trích xuất dữ kiện kiến trúc từ một repository và khi dẫn nguồn hoặc đánh dấu chúng.
4
+
5
+ ## Dữ kiện đến từ đâu
6
+ | Dữ kiện | Bằng chứng chính |
7
+ |---|---|
8
+ | Ngôn ngữ, runtime, package | Manifest và lockfile (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`) |
9
+ | Đơn vị runtime và cách khởi động | Entry point (`bin`, `main`, `scripts`), Dockerfile, config process hoặc service |
10
+ | Ranh giới module | Config workspace, export của package, file khai báo sở hữu thư mục, quy tắc lint về import |
11
+ | Phụ thuộc giữa các module | Câu lệnh import và đồ thị build; ưu tiên output của công cụ dựng đồ thị đang có |
12
+ | Bề mặt HTTP hoặc RPC | File đăng ký route, file OpenAPI hoặc proto, test của handler |
13
+ | Hình dạng dữ liệu | Schema, migration, định nghĩa type, validator |
14
+ | Hệ thống bên ngoài | Cấu hình client, các chỗ đọc biến môi trường, manifest triển khai |
15
+ | Quy ước | Mẫu lặp lại ở ba chỗ trở lên, config lint và format |
16
+ | Quyết định | ADR đang có, commit message phát biểu một lựa chọn, xác nhận từ người dùng |
17
+
18
+ Test là bằng chứng về hành vi mong muốn; config là bằng chứng về cái đang được triển khai chỉ
19
+ khi đường deploy thực sự đọc nó.
20
+
21
+ ## Các bước trích xuất
22
+ 1. Bắt đầu từ entry point rồi lần theo import ra ngoài; đừng bắt đầu từ tên thư mục.
23
+ 2. Đếm trước khi khái quát: một lần xuất hiện là một ví dụ, không phải một quy ước.
24
+ 3. Dùng câu lệnh chỉ đọc (tìm, liệt kê, công cụ dựng đồ thị hay build của chính project); đừng
25
+ cài thêm bộ phân tích.
26
+ 4. Ghi lại câu lệnh và kết quả cho mọi dữ kiện không hiển nhiên.
27
+
28
+ ## Cách dẫn nguồn
29
+ - Trong dòng: `The daemon owns session state (packages/daemon/src/sessions.js).`
30
+ - Kèm symbol: `(packages/core/src/tasks.js, createTask)`.
31
+ - Kèm số dòng chỉ khi chúng ổn định: `(src/router.ts:40-62)`.
32
+ - Nhiều nguồn: liệt kê nguồn trực tiếp nhất trước.
33
+ - Đường dẫn tương đối từ root của repository; không dùng đường dẫn tuyệt đối hay gắn với một
34
+ máy.
35
+
36
+ ## Đánh dấu điều chưa biết
37
+ - Trong dòng: `Unverified: the worker appears to retry three times (src/worker.js:88); no test covers it.`
38
+ - Cuối mục: danh sách `Open questions`, mỗi mục kèm người có thể trả lời và bằng chứng nào sẽ
39
+ giải quyết nó.
40
+ - Không bao giờ nâng một phát biểu chưa kiểm chứng lên thành dữ kiện mà không có bằng chứng
41
+ mới.
42
+
43
+ ## Dấu hiệu đáng ngại
44
+ - Một phát biểu không có đường dẫn, hoặc một đường dẫn không còn tồn tại.
45
+ - Những chữ như "should", "will", "designed to" dùng để mô tả hành vi hiện tại.
46
+ - Một sơ đồ hay danh sách module sao từ tài liệu cũ mà không kiểm lại cây nguồn.
47
+ - Config cho một service mà không có gì khởi động hay triển khai.
48
+ - Quy ước được ghi từ một file duy nhất, hoặc từ một style guide mà code bỏ ngoài tai.
49
+ - Tên host nội bộ, secret hay dữ liệu khách hàng: hãy xoá chúng.
@@ -1,44 +1,45 @@
1
1
  ---
2
2
  name: bug-loop
3
- description: Diagnose a bug or regression through a reproducible feedback loop, competing explanations, and verified correction. Use for failing tests, incorrect behavior, or performance regressions; read-only assignments stop before modifying project artifacts.
3
+ description: Chẩn đoán một bug hay regression bằng một vòng lặp phản hồi tái lập được, các cách giải thích cạnh tranh nhau, và bản sửa đã được kiểm chứng. Dùng khi test fail, khi hành vi sai, hoặc khi có regression về hiệu năng; việc được giao ở dạng chỉ đọc thì dừng trước khi sửa artifact của project.
4
4
  ---
5
5
 
6
- # Establish a failing loop, then fix the cause
7
-
8
- Start from the reported behavior and the assigned scope. Find the smallest useful
9
- command, request, replay, or test that distinguishes the bug from correct behavior.
10
- Run it and record the actual result before claiming reproduction. For intermittent
11
- failures, record conditions, seed when applicable, and observed failure frequency.
12
-
13
- If reproduction needs unavailable credentials, hardware, data, or a user action,
14
- report the specific gap to the assigning agent; main handles user communication.
15
- Continue useful in-scope investigation, but label an unconfirmed hypothesis as such.
16
- Do not claim a fix was verified without a meaningful observable check.
17
-
18
- Reduce the reproducer without removing the failure. Form competing explanations
19
- where the cause is uncertain, each with an observable prediction. Probe the few
20
- points that distinguish them; change one variable at a time. Prefer measured
21
- evidence over accumulating workarounds for the same unexplained symptom.
22
-
23
- Use isolated scratch space for disposable experiments. A read-only assignment can
24
- inspect and diagnose; it does not authorize instrumentation edits to project code.
25
- For performance work, compare equivalent workloads and record relevant conditions
26
- so that a timing difference is not mistaken for a causal improvement.
27
-
28
- Once a cause is established and writing is authorized:
29
-
30
- 1. Put a regression check at the seam that reproduces the actual failure.
31
- 2. Confirm that the check fails for the reported reason on the broken behavior.
32
- 3. Make the smallest correction consistent with the intended contract.
33
- 4. Run the check again, then relevant surrounding checks and the original scenario.
34
- 5. Remove temporary instrumentation and restore any deliberate fault injection.
35
-
36
- Read [test proof](references/test-proof.md) when designing/reviewing the regression
37
- test or when it passes before the fix. Do not weaken expectations, skip failing
38
- checks, or mock away the behavior to manufacture a pass. A changed requirement must
39
- be established independently of what the implementation currently returns.
40
-
41
- Return the reproduction command and result, established cause or remaining
42
- hypotheses, changed artifacts, before/after checks, limits, and unresolved risks.
43
- A peer returns to lead; lead returns to main. Read-only investigation returns
44
- diagnostic evidence and a proposed correction, not an imaginary code change.
6
+ # Dựng một vòng lặp fail trước, rồi sửa nguyên nhân
7
+
8
+ Bắt đầu từ hành vi được báo và phạm vi được giao. Tìm câu lệnh, request, bản replay
9
+ hay test nhỏ nhất mà vẫn hữu ích để phân biệt bug với hành vi đúng. Chạy nó và ghi lại
10
+ kết quả thực tế trước khi tuyên bố đã tái lập được. Với lỗi chập chờn, hãy ghi lại điều
11
+ kiện, seed khi có, và tần suất fail quan sát được.
12
+
13
+ Nếu việc tái lập cần credential, phần cứng, dữ liệu hay một hành động của người dùng mà
14
+ bạn không có, hãy báo đúng chỗ thiếu đó cho agent giao việc; main lo phần giao tiếp với
15
+ người dùng. Vẫn tiếp tục điều tra hữu ích trong phạm vi, nhưng hãy ghi rõ giả thuyết nào
16
+ chưa được xác nhận. Đừng tuyên bố một bản sửa đã được kiểm chứng khi chưa có một phép
17
+ kiểm quan sát được và có ý nghĩa.
18
+
19
+ Thu nhỏ bản tái lập mà không làm mất lỗi. Ở chỗ nguyên nhân còn chưa chắc, hãy dựng các
20
+ cách giải thích cạnh tranh nhau, mỗi cách kèm một dự đoán quan sát được. Thăm dò vài điểm
21
+ phân biệt được chúng; đổi mỗi lần một biến. Ưu tiên bằng chứng đo được hơn là chồng thêm
22
+ các cách lách cho cùng một triệu chứng chưa giải thích được.
23
+
24
+ Dùng không gian scratch riêng biệt cho các thí nghiệm dùng một lần. Việc được giao ở dạng
25
+ chỉ đọc có thể xem xét và chẩn đoán; nó không cho phép sửa code của project để chèn công
26
+ cụ đo. Với việc về hiệu năng, hãy so các khối việc tương đương và ghi lại các điều kiện
27
+ liên quan, để một chênh lệch thời gian không bị hiểu nhầm thành cải thiện có nhân quả.
28
+
29
+ Khi nguyên nhân đã được xác lập và bạn đã được cấp quyền ghi:
30
+
31
+ 1. Đặt một phép kiểm regression ngay tại đường ráp tái lập được lỗi thực tế.
32
+ 2. Xác nhận phép kiểm đó fail đúng vì lý do đã báo trên hành vi bị lỗi.
33
+ 3. Làm bản sửa nhỏ nhất mà vẫn nhất quán với contract dự kiến.
34
+ 4. Chạy lại phép kiểm đó, rồi các phép kiểm liên quan xung quanh và tình huống ban đầu.
35
+ 5. Bỏ công cụ đo tạm thời và hoàn lại mọi chỗ cố tình chèn lỗi.
36
+
37
+ Đọc [test proof](references/test-proof.md) khi thiết kế/review test regression, hoặc khi
38
+ nó pass ngay trước lúc sửa. Đừng làm yếu kỳ vọng, đừng bỏ qua phép kiểm đang fail, và đừng
39
+ mock cho hành vi biến đi để tạo ra một lần pass. Một yêu cầu đã thay đổi phải được xác lập
40
+ độc lập với cái mà implementation hiện trả về.
41
+
42
+ Trả về câu lệnh tái lập và kết quả, nguyên nhân đã xác lập hoặc các giả thuyết còn lại,
43
+ artifact đã thay đổi, phép kiểm trước/sau, các giới hạn, và rủi ro chưa xử lý.
44
+ Peer trả về cho lead; lead trả về cho main. Điều tra ở dạng chỉ đọc trả về bằng chứng
45
+ chẩn đoán và một bản sửa đề xuất, không phải một thay đổi code tưởng tượng.
@@ -1,25 +1,27 @@
1
- # Evidence for a regression correction
1
+ # Bằng chứng cho một bản sửa regression
2
2
 
3
- Choose an observable boundary close enough to isolate the failure but broad enough
4
- to exercise its real cause. A unit test of one caller cannot establish a bug that
5
- depends on ordering across several callers.
3
+ Chọn một biên quan sát được, đủ gần để khoanh được lỗi nhưng đủ rộng để kích hoạt đúng
4
+ nguyên nhân thật của nó. Một unit test của một bên gọi không thể xác lập một bug phụ
5
+ thuộc vào thứ tự giữa nhiều bên gọi.
6
6
 
7
- Expected behavior comes from the user request, a supported contract, or independently
8
- derived examples. Do not calculate the expected result using the implementation
9
- being tested. Mock external boundaries only where doing so leaves the claimed
10
- behavior under test.
7
+ Hành vi mong đợi đến từ yêu cầu của người dùng, từ một contract được hỗ trợ, hoặc từ các
8
+ ví dụ suy ra một cách độc lập. Đừng tính kết quả mong đợi bằng chính implementation đang
9
+ được kiểm. Chỉ mock các biên bên ngoài ở chỗ việc mock vẫn giữ được hành vi được tuyên bố
10
+ nằm trong phạm vi kiểm.
11
11
 
12
- Describe proof accurately:
12
+ Hãy mô tả bằng chứng cho chính xác:
13
13
 
14
- - Green only: the current check passes; this alone does not show regression coverage.
15
- - Red -> green: the check fails on broken behavior and passes after the correction.
16
- - Fault injection: where justified by risk, restore the specific defect in an
17
- isolated copy, confirm failure, restore the fix, and confirm success again.
14
+ - Chỉ xanh: phép kiểm hiện tại pass; chỉ riêng điều này không cho thấy có phủ regression.
15
+ - Đỏ -> xanh: phép kiểm fail trên hành vi bị lỗi và pass sau khi sửa.
16
+ - Chèn lỗi: ở chỗ rủi ro biện minh được, hãy dựng lại đúng khuyết điểm đó trong một bản
17
+ sao riêng, xác nhận nó fail, hoàn lại bản sửa, rồi xác nhận nó thành công lần nữa.
18
18
 
19
- Fault injection is optional unless the assignment requires it. Never mutate another
20
- writer's checkout, discard unrelated work, or leave deliberately broken code in the
21
- deliverable. State an unavailable pre-fix run or missing test seam as a limitation.
19
+ Chèn lỗi là tuỳ chọn, trừ khi việc được giao bắt buộc. Đừng bao giờ sửa checkout của người
20
+ ghi khác, đừng bỏ đi công việc không liên quan, và đừng để lại code cố tình làm sai trong
21
+ sản phẩm giao. Hãy nêu rõ như một giới hạn khi không chạy được bản trước khi sửa hoặc khi
22
+ thiếu đường ráp để test.
22
23
 
23
- Keep the actual commands, results, and relevant environment conditions. Screenshots,
24
- logs, and manually observed behavior can supplement tests; do not relabel them as
25
- automated proof. A passing check and an independent acceptance decision are separate.
24
+ Giữ lại đúng các câu lệnh, kết quả, và các điều kiện môi trường liên quan. Ảnh chụp màn
25
+ hình, log và hành vi quan sát bằng tay có thể bổ trợ cho test; đừng dán nhãn chúng thành
26
+ bằng chứng tự động. Một phép kiểm pass và một quyết định nghiệm thu độc lập là hai chuyện
27
+ khác nhau.
@@ -0,0 +1,34 @@
1
+ ---
2
+ name: compact
3
+ description: "Viết checkpoint có cấu trúc trước khi compact context của main, để sau khi nén vẫn tiếp tục đúng việc. Dùng khi runtime báo context gần đầy (khoảng 70%), khi người dùng yêu cầu compact, hoặc trước khi chuyển phiên."
4
+ ---
5
+
6
+ # Compact
7
+
8
+ ## Khi dùng
9
+ - Runtime báo context dùng khoảng 70% hoặc hơn, hay yêu cầu viết checkpoint.
10
+ - Người dùng yêu cầu compact.
11
+ - Trước khi kết thúc hoặc chuyển phiên.
12
+
13
+ Không compact khi đang giữ lượt (alp_wait, alp_ask, delegate wait), hoặc khi đang viết dở câu trả lời. Phải trả lời người dùng trước.
14
+
15
+ ## Quy trình
16
+ 1. **Kiểm thực tế, không chép trí nhớ.** Đọc alp_task ready/list và alp_board. Với PR/CI liên quan, chạy gh pr view/checks ngay trong lượt.
17
+ 2. **Viết checkpoint theo đúng các mục sau** (ngắn, có ID, có giờ):
18
+ - **Người dùng và ngôn ngữ:** profile (Phở/Cafe), ngôn ngữ trả lời.
19
+ - **Assignment đang chạy:** assignmentId, agent, taskId, worktree hoặc nhánh, ETA, note cuối kèm giờ.
20
+ - **Task và gate:** task đang làm hoặc chờ review; gate đang mở kèm nội dung; gate đã có quyết định nhưng chưa gỡ.
21
+ - **Quyết định của người dùng:** trích nguyên văn, kèm giờ và task nhận quyết định đó.
22
+ - **Câu hỏi đang chờ người dùng:** câu hỏi nào, ở gate nào.
23
+ - **PR/CI:** số PR, head SHA, trạng thái check đã kiểm lúc nào, watcher nền (job id) nếu có.
24
+ - **Rủi ro và giới hạn còn mở:** từng mục, kèm task theo dõi.
25
+ - **Bước tiếp theo:** theo thứ tự, ai làm.
26
+ 3. **Không đưa vào checkpoint:** bài học, skill, nội dung task đầy đủ (đã lưu ngoài context), log dài, secret.
27
+ 4. Gửi checkpoint cho runtime theo yêu cầu, hoặc ghi alp_pin/task note nếu compact thủ công. Sau đó báo người dùng một dòng: "Em đã compact context; checkpoint giữ X assignment, Y gate, Z quyết định."
28
+
29
+ ## Kiểm chứng
30
+ - Mọi assignment đang chạy đều có ID.
31
+ - Mọi gate mở và mọi câu hỏi đang chờ đều có trong checkpoint.
32
+ - Quyết định của người dùng được trích nguyên văn, không diễn giải.
33
+ - Trạng thái PR/CI ghi rõ thời điểm đã kiểm.
34
+ - Sau compact, lượt đầu tiên đọc lại alp_task và gh trước khi báo trạng thái.
@@ -0,0 +1,36 @@
1
+ ---
2
+ name: curate
3
+ description: "Rà soát toàn bộ bài học (lesson) và skill: gộp lesson trùng, rút gọn lesson dài, bỏ lesson đã có skill thay, đề xuất cho nghỉ skill không còn cần, và đề xuất issue cho ALP. Dùng khi người dùng yêu cầu rà soát, hoặc khi lịch curate hằng tháng đánh thức main."
4
+ ---
5
+
6
+ # Curate
7
+
8
+ ## Khi dùng
9
+ - Người dùng yêu cầu rà soát, dọn dẹp hay rút gọn lesson và skill.
10
+ - Main được đánh thức bởi lịch curate hằng tháng (prompt có `[alp-curate]`).
11
+
12
+ Không làm khi đang giữ một gate hay câu hỏi khác với người dùng; trả lời việc đó trước.
13
+
14
+ ## Quy trình
15
+ 1. **Đọc hết, không nhớ lại.** Đọc `.alp/lessons.md` của project và `~/.alp/lessons.md` của người dùng; đọc mọi SKILL.md trong `~/.alp/skills`, `.alp/skills` và danh sách skill của từng role (`role-skills.json`).
16
+ 2. **Lập đề xuất, mỗi mục một dòng lý do:**
17
+ - **Gộp:** các lesson cùng ý thành một rule.
18
+ - **Rút gọn:** lesson dài hoặc lan man thành một rule ngắn: làm gì, khi nào.
19
+ - **Xóa:** lesson đã được một skill bao trọn (nêu tên skill), hoặc đã lỗi thời.
20
+ - **Thành skill:** 3 lesson trở lên cùng chủ đề thì gom thành skill qua `alp_skill` (truyền `lessons` để bỏ chúng).
21
+ - **Skill không còn cần:** trùng skill khác, không role nào dùng, hay đã lỗi thời. Nêu lý do và đề xuất cho nghỉ qua `alp_skill_retire`.
22
+ - **Đề xuất cho ALP:** lesson hay skill hữu ích cho mọi người dùng, hoặc chỗ ALP còn thiếu.
23
+ 3. **Gửi qua cổng duyệt, không hỏi trước trong chat.** Tóm tắt đề xuất trong một tin, rồi gọi ngay các tool bên dưới. Lần duyệt trong tool là lần duyệt duy nhất; người dùng từ chối hay góp ý thì sửa và đề xuất lại.
24
+ 4. **Các tool:**
25
+ - Lesson: một lần gọi `alp_lesson_curate` với mọi thay đổi (remove là văn bản đúng nguyên văn; add là rule thay thế khi gộp hoặc rút gọn). ALP hiện toàn bộ thay đổi trong một lần duyệt.
26
+ - Skill mới: `alp_skill`.
27
+ - Skill không còn cần: `alp_skill_retire` từng skill (name, reason). Chỉ khi người dùng duyệt, ALP mới chuyển nó sang `retired-skills` (vẫn giữ, khôi phục được) và bỏ khỏi `role-skills.json`.
28
+ - Issue: `alp_issue` action search target alp trước; chưa có thì create, đã có thì comment. Người dùng duyệt từng bản nháp.
29
+ 5. Báo kết quả một đoạn ngắn: đã gộp, rút gọn, xóa bao nhiêu; skill nào được cho nghỉ; issue nào đã tạo.
30
+
31
+ ## Kiểm chứng
32
+ - Không sửa hay xóa lesson nào ngoài `alp_lesson_curate`; không sửa file lesson trực tiếp.
33
+ - Mỗi rule sau gộp vẫn giữ đủ ý của các lesson gốc.
34
+ - Mỗi lesson bị xóa vì skill đều nêu đúng tên skill thay nó.
35
+ - Issue không chứa secret, đường dẫn riêng hay nội dung project của người dùng.
36
+ - Không có thay đổi nào khi người dùng chưa duyệt; lesson không tìm thấy được báo lại, không đoán.
@@ -0,0 +1,90 @@
1
+ ---
2
+ name: feature-architecture
3
+ description: "Hiện thực một feature mới sao cho nó khớp với các quy tắc kiến trúc, boilerplate và hướng phụ thuộc đang có của project, với một bản thiết kế ngắn trước và các phép kiểm ranh giới sau. Dùng khi thêm feature vào một codebase có tài liệu kiến trúc, ADR, template hoặc một contract về ranh giới. Không dùng cho việc cấu trúc lại mà giữ nguyên hành vi (safe-refactor) hay sửa một regression (bug-loop)."
4
+ ---
5
+
6
+ # Kiến trúc feature
7
+
8
+ ## Khi dùng
9
+
10
+ - Một feature, endpoint, module hay câu lệnh mới phải đưa được vào một project đã có
11
+ tài liệu kiến trúc, ADR, quy tắc về lớp hoặc package, hay boilerplate cho feature.
12
+ - Một architect hoặc reviewer chỉ đọc được hỏi xem một feature đã lên kế hoạch có khớp
13
+ với kiến trúc của project hay không (chỉ tư vấn).
14
+
15
+ ## Không dùng cho
16
+
17
+ - Cấu trúc lại code đang có mà không đổi hành vi: dùng safe-refactor.
18
+ - Tái lập và sửa một bug hay regression: dùng bug-loop.
19
+ - Viết hay sắp xếp lại chính tài liệu kiến trúc: dùng architecture-docs.
20
+ - Chọn một phong cách kiến trúc mới cho project: đó là quyết định của người dùng.
21
+
22
+ ## Điều kiện tiên quyết
23
+
24
+ - Một phạm vi được giao (đường dẫn hoặc module) và tiêu chí nghiệm thu lấy từ brief.
25
+ - Quyền đọc ALP.md, hướng dẫn của project, và tài liệu kiến trúc nếu có.
26
+
27
+ ## Quy trình
28
+
29
+ 1. Đọc ALP.md và hướng dẫn riêng của project; ghi lại câu lệnh build, test, lint và
30
+ kiểm ranh giới.
31
+ 2. Đọc các tài liệu kiến trúc liên quan (ví dụ `docs/architecture/`, các ADR, README của
32
+ package). Chỉ đọc phần dính tới các module mà feature này chạm vào.
33
+ 3. Liệt kê các quy tắc thành hai nhóm. Ràng buộc cứng: quy tắc phụ thuộc, chỗ đặt file,
34
+ tương thích public API, interface hay điểm đăng ký bắt buộc. Quy ước mềm: cách đặt tên,
35
+ hình dạng thư mục, phong cách test. Dẫn nguồn của từng quy tắc.
36
+ 4. Tìm boilerplate hoặc template (ví dụ `templates/features/`) và feature đang có giống
37
+ nhất. Lặp lại cấu trúc, cách nối dây và test của nó.
38
+ 5. Vẽ ra các module bị chạm và hướng của từng phụ thuộc mới. Một cạnh mới phải chỉ cùng
39
+ hướng với các cạnh cùng loại đang có.
40
+ 6. Viết một bản thiết kế feature ngắn: file sẽ thêm hoặc sửa, module sở hữu, bề mặt public,
41
+ test. Đặt nó vào brief của lead/peer hoặc vào note của task.
42
+ 7. Hiện thực theo các quy ước đang có. Ở trong các đường dẫn sở hữu.
43
+ 8. Chạy các phép kiểm kiến trúc. Dùng công cụ lint và kiểm ranh giới của chính project
44
+ trước. Nếu project đã nhận file contract của ALP, hãy chạy thêm
45
+ `node <this skill dir>/scripts/check-boundaries.mjs --root <repo>`; mặc định nó đọc
46
+ `docs/architecture/contract.json` và thoát với mã 1 khi có vi phạm. Xem
47
+ [scripts/check-boundaries.mjs](scripts/check-boundaries.mjs).
48
+ 9. Review diff đối chiếu với bản thiết kế. Chỉ cập nhật tài liệu kiến trúc hoặc contract
49
+ nếu một ranh giới hay contract thật sự đã đổi.
50
+
51
+ Một architect hoặc reviewer chỉ đọc chạy bước 1-6 và 8 trên bản đề xuất hoặc trên cây hiện
52
+ tại, rồi báo phát hiện và một bản thiết kế được khuyến nghị, thay vì sửa file.
53
+
54
+ ## Ràng buộc
55
+
56
+ - Đừng bao giờ áp đặt Clean Architecture, DDD, Hexagonal, hay bất kỳ framework hoặc mẫu nào
57
+ mà project chưa dùng.
58
+ - Đừng thêm một abstraction, lớp hay interface chỉ để thoả một mẫu chung chung.
59
+ - Nếu kiến trúc không thể thoả yêu cầu, hãy dừng. Nêu rõ xung đột, cái được cái mất, và các
60
+ phương án, rồi chuyển quyết định lên trên
61
+ (peer -> lead -> main -> người dùng).
62
+ - Một ngoại lệ với quy tắc cứng cần một quyết định được ghi lại rõ ràng (một ADR hoặc một
63
+ note trong task nêu tên người đã duyệt). Đừng bao giờ lách một quy tắc trong im lặng, và
64
+ đừng sửa contract hay config lint để một vi phạm lọt qua.
65
+ - Các agent chỉ đọc (architect, reviewer) báo phát hiện; họ không sửa file.
66
+ - Skill này không cấp quyền cài công cụ, mở rộng phạm vi, hay ghi ra ngoài các đường dẫn
67
+ sở hữu.
68
+
69
+ ## Kiểm chứng
70
+
71
+ - Lint, type check, test và công cụ kiểm ranh giới của project đều pass trên cây cuối cùng.
72
+ - `check-boundaries.mjs` thoát với mã 0 khi project dùng file contract.
73
+ - Mọi cạnh phụ thuộc mới khớp với hướng đã vẽ ở bước 5.
74
+ - Handoff: câu lệnh kiểm kèm output, các file đã đổi nhóm theo module, và mọi ngoại lệ đã
75
+ được duyệt kèm nơi ghi nó và người duyệt.
76
+
77
+ ## Xử lý khi thất bại
78
+
79
+ - Vi phạm ranh giới: di chuyển code hoặc đảo hướng phụ thuộc theo cách feature tương tự đã
80
+ làm; chạy lại bộ kiểm. Đừng làm yếu quy tắc.
81
+ - Không có feature hay template tương tự: hãy nói thẳng, đề xuất phương án gần nhất, và hỏi
82
+ agent giao việc trước khi tự dựng một cấu trúc mới.
83
+ - Tài liệu và code xung đột: theo code mà các phép kiểm thực thi, ghi lại chỗ lệch, và báo lên.
84
+ - Bộ kiểm thiếu hoặc chạy không được: báo đúng câu lệnh và lỗi; đừng tuyên bố là đã kiểm
85
+ chứng được các ranh giới.
86
+
87
+ ## Tài liệu tham chiếu
88
+
89
+ - [references/feature-design.md](references/feature-design.md) — đọc khi viết bản thiết kế feature (bước 6), khi chọn feature tương tự (bước 4), hoặc khi kiểm hướng phụ thuộc (bước 5).
90
+ - [references/architecture-contract.md](references/architecture-contract.md) — đọc khi project đã có hoặc muốn có một contract kiến trúc máy kiểm được.
@@ -0,0 +1,95 @@
1
+ # Contract kiến trúc
2
+
3
+ Đọc khi project đã có `docs/architecture/contract.json`, hoặc muốn có các quy tắc phụ thuộc
4
+ mà một công cụ kiểm thay vì để reviewer phải nhớ.
5
+
6
+ ## Ưu tiên công cụ của chính project
7
+
8
+ Nếu project đã thực thi ranh giới sẵn (một quy tắc boundaries hay import của ESLint,
9
+ dependency-cruiser, Nx module boundaries, import-linter cho Python, ArchUnit cho Java,
10
+ hay một script riêng như `scripts/check-boundaries.mjs` của chính nó), hãy dùng nó và
11
+ dừng ở đây. Contract dưới đây là phương án dự phòng cho các repository JavaScript/TypeScript
12
+ chưa có gì. Việc nhận nó là quyết định của project: hãy đề xuất, đừng tự thêm vào.
13
+
14
+ ## Định dạng
15
+
16
+ ```json
17
+ {
18
+ "description": "Layers of the orders service",
19
+ "modules": {
20
+ "api": ["src/api/**"],
21
+ "app": ["src/app/**"],
22
+ "domain": ["src/domain/**"],
23
+ "shared": ["src/shared/**"]
24
+ },
25
+ "allow": {
26
+ "api": ["app", "shared"],
27
+ "app": ["domain", "shared"],
28
+ "domain": ["shared"],
29
+ "shared": []
30
+ },
31
+ "denyPackages": { "domain": ["express", "pg", "node:fs"] },
32
+ "ignore": ["**/*.test.ts", "**/__fixtures__/**"],
33
+ "exceptions": [
34
+ { "file": "src/domain/legacy-report.ts", "import": "src/api/**",
35
+ "reason": "Report export predates the layering; removed by #412", "approvedBy": "main, 2026-11-05",
36
+ "expires": "2027-03-31" }
37
+ ]
38
+ }
39
+ ```
40
+
41
+ - `modules`: tên -> các glob trên đường dẫn POSIX tương đối với repository (`**`, `*`, `?`).
42
+ Một file thuộc module đầu tiên có glob khớp; file không thuộc module nào thì không bị kiểm.
43
+ - `allow`: một module được liệt kê chỉ được import chính nó và các module được nêu tên. Module
44
+ không có trong `allow` thì không bị hạn chế, nên hãy liệt kê mọi module bạn muốn ràng buộc.
45
+ - `denyPackages`: tên package trần (hoặc builtin `node:`) mà một module không được import.
46
+ - `ignore`: các file không bao giờ bị kiểm.
47
+ - `exceptions`: bản ghi của việc chuyển lên. Mỗi mục cần `file` (một file, không dùng pattern),
48
+ `import` (một glob trên file bị import, hoặc một tên package; đừng bao giờ dùng `**`),
49
+ `reason` và `approvedBy`, và có thể có `expires` (YYYY-MM-DD; sau ngày đó nó không miễn gì
50
+ nữa). Chỉ thêm một mục sau khi quyết định đã được người sở hữu quy tắc đó đưa ra, đừng bao
51
+ giờ thêm để tự mình làm một phép kiểm đang fail lọt qua. Bộ kiểm sẽ liệt kê các exception
52
+ không ai cần.
53
+
54
+ ## Thay đổi contract thì phải được review
55
+
56
+ Làm yếu contract (thêm một exception, nới `allow`, bỏ một package bị cấm, thêm một `ignore`,
57
+ đổi một module) sẽ làm mọi phép kiểm pass, nên đó là một quyết định giống như một exception.
58
+ Với `--base <git-ref>`, bộ kiểm so contract với bản ở ref đó và fail (thoát mã 1) với mọi chỗ
59
+ nới lỏng nó tìm thấy, nêu tên từng chỗ, cho tới khi lần chạy nói ra ai đã review
60
+ nó: `--approved-by "main, 2026-11-05"`. Siết chặt thì không cần review. Các gate chạy với
61
+ `--base` (`main` cho nhánh của một việc được giao, `origin/main` trong CI) và không bao giờ với
62
+ `--approved-by`; reviewer chạy cờ đó sau khi đã quyết.
63
+
64
+ ## Bộ kiểm thấy những gì
65
+
66
+ `node <skill dir>/scripts/check-boundaries.mjs --root <repo> [--contract FILE] [--base REF [--approved-by NAME]] [--json]`
67
+
68
+ - Đọc `import ... from`, `export ... from`, `import '...'` dạng side-effect, `import('...')`
69
+ động và `require('...')`, bỏ qua comment, trong các file `.js .jsx .mjs .cjs .ts
70
+ .tsx .mts .cts` (bỏ qua `.d.ts`, `node_modules`, `dist`, `build`, `coverage`).
71
+ - Phân giải các specifier tương đối theo cách Node và TypeScript làm (phần mở rộng, `index.*`,
72
+ `./x.js` cho `./x.ts`). Alias đường dẫn (`@/x`, `paths` trong tsconfig) và specifier được
73
+ tính ra lúc chạy thì không được phân giải: project dùng alias cần công cụ riêng của nó.
74
+ - Thoát mã 0 là sạch, 1 là có vi phạm (`file:line from -> to (specifier): rule`) hoặc có một
75
+ chỗ nới lỏng chưa được review, 2 là contract, tham số hay base không hợp lệ. Nó chỉ đọc file
76
+ (và `git show <base>:<contract>`).
77
+
78
+ ## Thực thi nó
79
+
80
+ Chỉ những quy tắc bộ kiểm xác minh được một cách đáng tin mới thuộc về một gate cứng.
81
+
82
+ - CI: thêm câu lệnh vào CI hoặc script test của project, với script được sao vào chính
83
+ repository (ví dụ `tools/check-boundaries.mjs`) để CI không cần thư viện ALP.
84
+ - ALP: một hook dạng blocking sẽ chặn một handoff, một lần đóng task hay một lần merge khi phép
85
+ kiểm còn fail; phần cuối output của nó là lý do agent đọc được. Một hook áp dụng cho các
86
+ agent nêu tên nó, nên người dùng (không phải agent) định nghĩa hook và cấp cho họ:
87
+
88
+ ```sh
89
+ alp hook add architecture --project --event handoff --command "node tools/check-boundaries.mjs --base main" --blocking --timeout 120
90
+ alp agent edit peer --project --hooks architecture
91
+ alp hook test architecture --project
92
+ ```
93
+
94
+ Dùng `--event task.close` (trên main hoặc lead) hay `--event merge` cho các gate còn lại.
95
+ Hook của project chỉ chạy khi người dùng đã tin workspace (`alp trust`).
@@ -0,0 +1,69 @@
1
+ # Thiết kế feature
2
+
3
+ Đọc khi viết bản thiết kế feature, khi chọn feature tương tự, hoặc khi kiểm hướng của phụ thuộc mới.
4
+
5
+ ## Chọn feature tương tự
6
+
7
+ Xếp hạng các ứng viên theo số điểm sau mà chúng chia sẻ với feature mới:
8
+
9
+ 1. Cùng loại entry point (route HTTP, câu lệnh CLI, job, màn hình UI, event handler).
10
+ 2. Cùng module hay lớp sở hữu, và cùng tập module mà nó phụ thuộc vào.
11
+ 3. Cùng hình dạng lưu trữ hay tích hợp (đọc/ghi cùng một store hay service).
12
+ 4. Mới được viết hoặc mới bị chạm tới, nên nó phản ánh quy ước hiện hành.
13
+ 5. Có test theo phong cách project mong đợi.
14
+
15
+ Ưu tiên boilerplate hay generator của project khi có; dùng feature tương tự để bù phần
16
+ template bỏ sót. Nếu hai ứng viên mâu thuẫn nhau, hãy theo cái mà tài liệu kiến trúc hoặc
17
+ các phép kiểm hậu thuẫn, và ghi lại cái kia như một chỗ lệch.
18
+
19
+ Ghi lại lựa chọn đó trong bản thiết kế: "Mirrors `<path>` because <shared traits>."
20
+
21
+ ## Mẫu thiết kế
22
+
23
+ Giữ nó vừa đủ cho những gì một reviewer cần để kiểm implementation. Bỏ các mục trống.
24
+
25
+ ```text
26
+ Feature: <one-line purpose>
27
+ Owning module: <module/package/layer>
28
+ Mirrors: <path of analogous feature or template> because <traits>
29
+
30
+ Hard constraints applied:
31
+ - <rule> (source: <doc/ADR/lint config>)
32
+
33
+ Files:
34
+ - add <path> <role in the feature>
35
+ - change <path> <what changes and why>
36
+
37
+ Public surface:
38
+ - <exported symbol / route / CLI flag / config key / event> new | changed
39
+ - Compatibility: <none affected | what callers must change>
40
+
41
+ Dependencies (from -> to):
42
+ - <module A> -> <module B> <existing edge kind it matches>
43
+
44
+ Tests:
45
+ - <test file> <behavior covered>
46
+
47
+ Open decisions / exceptions:
48
+ - <question or rule exception, who must decide>
49
+ ```
50
+
51
+ ## Danh sách kiểm hướng phụ thuộc
52
+
53
+ Trả lời từng câu cho mỗi import, lời gọi hay lần đăng ký mới:
54
+
55
+ - Đã có một cạnh cùng loại chỉ theo hướng này chưa? Dẫn ra một cạnh.
56
+ - Cạnh đó có vượt một ranh giới lớp hay package mà tài liệu hoặc contract hạn chế không?
57
+ - Nó có tạo ra một vòng lặp giữa các module không? Kiểm cả hai hướng.
58
+ - Một module thấp hơn hoặc dùng chung bây giờ có import từ một module feature hay app không?
59
+ - Code domain hay core bây giờ có import một chi tiết framework, transport hay lưu trữ mà
60
+ feature tương tự vẫn giữ ở ngoài không?
61
+ - Một dependency chỉ dùng cho test hay chỉ dùng khi dev có thể chạm tới được từ code production
62
+ không?
63
+ - Feature có thò vào phần nội bộ của module khác thay vì vào entry point public của nó không?
64
+ - Một lần đăng ký mới (router, danh sách plugin, DI container, manifest) có được đặt đúng chỗ
65
+ mà feature tương tự đăng ký không?
66
+
67
+ Bất kỳ câu "có" nào về một lần vượt ranh giới bị hạn chế, một vòng lặp, hay một lần truy cập
68
+ phần nội bộ đều là vấn đề ràng buộc cứng: hãy sửa chỗ đặt, hoặc chuyển một quyết định ngoại lệ
69
+ lên trên trước khi hiện thực.