@anhlp/alp-core 0.0.1-beta.6 → 0.0.1-beta.8

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 (135) hide show
  1. package/dist/bridges.d.ts +5 -6
  2. package/dist/bridges.js +3 -4
  3. package/dist/library-edit.d.ts +51 -2
  4. package/dist/library-edit.js +160 -8
  5. package/dist/library.d.ts +14 -1
  6. package/dist/library.js +73 -5
  7. package/dist/models.d.ts +35 -0
  8. package/dist/models.js +17 -1
  9. package/dist/packaged.d.ts +37 -45
  10. package/dist/packaged.js +42 -156
  11. package/dist/packs.d.ts +57 -0
  12. package/dist/packs.js +247 -0
  13. package/dist/permissions.d.ts +3 -2
  14. package/dist/permissions.js +6 -3
  15. package/dist/profiles.js +6 -6
  16. package/dist/providers.d.ts +2 -5
  17. package/dist/providers.js +22 -6
  18. package/dist/skill-validate.d.ts +85 -0
  19. package/dist/skill-validate.js +298 -0
  20. package/dist/template-path.d.ts +2 -2
  21. package/dist/template-path.js +0 -5
  22. package/dist/types.d.ts +2 -0
  23. package/dist/upgrade.d.ts +10 -0
  24. package/dist/upgrade.js +112 -6
  25. package/dist/validation.js +6 -6
  26. package/package.json +18 -2
  27. package/src/bridges.js +9 -10
  28. package/src/library-edit.js +170 -8
  29. package/src/library.js +96 -6
  30. package/src/models.js +24 -0
  31. package/src/packaged.js +74 -191
  32. package/src/packs.js +246 -0
  33. package/src/permissions.d.ts +3 -2
  34. package/src/permissions.js +13 -3
  35. package/src/profiles.js +7 -7
  36. package/src/providers.js +22 -8
  37. package/src/resolver.js +1 -1
  38. package/src/skill-validate.js +287 -0
  39. package/src/template-path.js +1 -6
  40. package/src/types.d.ts +2 -0
  41. package/src/upgrade.js +54 -6
  42. package/src/validation.js +8 -7
  43. package/templates/ALP.md +52 -52
  44. package/templates/agents/lead/AGENT.md +77 -74
  45. package/templates/agents/main/AGENT.md +153 -145
  46. package/templates/agents/oracle/AGENT.md +38 -37
  47. package/templates/agents/peer/AGENT.md +56 -52
  48. package/templates/agents/reviewer/AGENT.md +63 -65
  49. package/templates/agents/supervisor/AGENT.md +63 -63
  50. package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
  51. package/templates/packs/architecture/agents/architect/agent.json +5 -0
  52. package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
  53. package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
  54. package/templates/packs/architecture/pack.json +7 -0
  55. package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
  56. package/templates/packs/architecture/teams/blueprint/team.json +19 -0
  57. package/templates/packs/backend/pack.json +6 -0
  58. package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
  59. package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
  60. package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
  61. package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
  62. package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
  63. package/templates/packs/backend/skills/databases/SKILL.md +103 -0
  64. package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
  65. package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
  66. package/templates/packs/design/pack.json +6 -0
  67. package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
  68. package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
  69. package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
  70. package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
  71. package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
  72. package/templates/packs/frontend/pack.json +6 -0
  73. package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
  74. package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
  75. package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
  76. package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
  77. package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
  78. package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
  79. package/templates/packs/integration/pack.json +6 -0
  80. package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
  81. package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
  82. package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
  83. package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
  84. package/templates/packs/operations/pack.json +6 -0
  85. package/templates/packs/operations/skills/devops/SKILL.md +85 -0
  86. package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
  87. package/templates/packs/operations/skills/devops/references/containers.md +85 -0
  88. package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
  89. package/templates/packs/operations/skills/devops/references/observability.md +86 -0
  90. package/templates/packs/quality/pack.json +6 -0
  91. package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
  92. package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
  93. package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
  94. package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
  95. package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
  96. package/templates/role-skills.json +4 -4
  97. package/templates/skills/architecture-docs/SKILL.md +81 -0
  98. package/templates/skills/architecture-docs/references/adr.md +62 -0
  99. package/templates/skills/architecture-docs/references/diagrams.md +60 -0
  100. package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
  101. package/templates/skills/bug-loop/SKILL.md +41 -40
  102. package/templates/skills/bug-loop/references/test-proof.md +21 -19
  103. package/templates/skills/compact/SKILL.md +2 -2
  104. package/templates/skills/curate/SKILL.md +6 -5
  105. package/templates/skills/feature-architecture/SKILL.md +90 -0
  106. package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
  107. package/templates/skills/feature-architecture/references/feature-design.md +69 -0
  108. package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
  109. package/templates/skills/goal-griller/SKILL.md +27 -27
  110. package/templates/skills/prompt-leverage/SKILL.md +29 -27
  111. package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
  112. package/templates/skills/release-readiness/SKILL.md +83 -0
  113. package/templates/skills/release-readiness/references/checklist.md +40 -0
  114. package/templates/skills/release-readiness/references/verdict-template.md +53 -0
  115. package/templates/skills/safe-refactor/SKILL.md +84 -0
  116. package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
  117. package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
  118. package/templates/skills/security-review/SKILL.md +87 -0
  119. package/templates/skills/security-review/references/checklist.md +74 -0
  120. package/templates/skills/security-review/references/severity.md +61 -0
  121. package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
  122. package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
  123. package/templates/skills/skill-authoring/SKILL.md +84 -0
  124. package/templates/skills/skill-authoring/references/evaluation.md +45 -0
  125. package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
  126. package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
  127. package/templates/skills/smart-commits/SKILL.md +37 -36
  128. package/templates/skills/test-strategy/SKILL.md +83 -0
  129. package/templates/skills/test-strategy/references/contract-tests.md +46 -0
  130. package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
  131. package/templates/skills/xia/SKILL.md +40 -38
  132. package/templates/teams/cafe/HOUSE_RULES.md +1 -1
  133. package/templates/teams/cafe/team.json +1 -1
  134. package/templates/teams/pho/HOUSE_RULES.md +1 -1
  135. package/templates/teams/pho/team.json +1 -1
@@ -0,0 +1,81 @@
1
+ ---
2
+ name: architecture-docs
3
+ description: "Tạo và bảo trì tài liệu kiến trúc dựa trên bằng chứng trong repository: tổng quan, ranh giới, phụ thuộc giữa các module, luồng dữ liệu, API contract, quyết định, ADR, sơ đồ Mermaid và quy ước. Dùng khi tài liệu còn thiếu, đã lỗi thời, hoặc khi một thay đổi làm đổi ranh giới hay contract. Không dùng để thiết kế feature mới (dùng feature-architecture) hay nghiên cứu khả năng tái dùng (dùng xia)."
4
+ ---
5
+
6
+ # Ghi lại kiến trúc mà code chứng minh được
7
+
8
+ ## Khi dùng
9
+ - Project chưa có tổng quan kiến trúc, hoặc bản đang có mâu thuẫn với code.
10
+ - Một thay đổi thêm, bỏ hoặc di chuyển ranh giới module, public API, schema hay luồng dữ liệu.
11
+ - Một quyết định về công nghệ hoặc cấu trúc đã được xác nhận và cần một ADR.
12
+ - Người bảo trì tài liệu hoặc reviewer được yêu cầu kiểm tra tài liệu kiến trúc xem có lệch.
13
+
14
+ ## Không dùng cho
15
+ - Thiết kế cách xây một feature mới: dùng feature-architecture.
16
+ - So sánh thư viện hay tìm code tái dùng được: dùng xia.
17
+ - Hướng dẫn người dùng, README và changelog không liên quan tới cấu trúc.
18
+ - Đoán ý định của code mà không ai giải thích được: hãy ghi lại một câu hỏi mở.
19
+
20
+ ## Điều kiện tiên quyết
21
+ - Đọc ALP.md và mọi index tài liệu, cây `docs/` hoặc hướng dẫn đóng góp đang có.
22
+ - Biết rõ các đường dẫn sở hữu (owned paths): người ghi chỉ sửa các file tài liệu được giao;
23
+ role chỉ đọc thì báo cáo.
24
+ - Xác định thay đổi hoặc câu hỏi đã kích hoạt công việc này; giới hạn phạm vi tài liệu theo đó.
25
+
26
+ ## Quy trình
27
+ 1. **Tìm bố cục.** Theo bố cục tài liệu project đang dùng. Nếu chưa có, hãy đề xuất
28
+ `docs/architecture/overview.md`, `boundaries.md`, `conventions.md` và
29
+ `decisions/NNNN-title.md`, và xác nhận trước khi tạo cấu trúc cấp cao mới.
30
+ 2. **Thu bằng chứng.** Đọc manifest, entry point, config build và deploy, file khai báo
31
+ route, schema, đồ thị import và test của khu vực trong phạm vi. Ghi mỗi dữ kiện kèm
32
+ đường dẫn file chứng minh nó.
33
+ 3. **Tổng quan.** Mục đích, các đơn vị runtime (process, package, service), chúng khởi động
34
+ và nói chuyện với nhau ra sao, và các hệ thống bên ngoài. Một trang ngắn.
35
+ 4. **Ranh giới và phụ thuộc.** Trách nhiệm của từng module, nó được import gì, ai import nó,
36
+ và bề mặt public mà người khác dựa vào. Ghi lại các vòng lặp và chỗ rò rỉ phát hiện được.
37
+ 5. **Luồng dữ liệu và contract.** Truy vết đường đi chính của request hoặc job từ đầu tới cuối.
38
+ Với mỗi API, event hay schema, dẫn file định nghĩa và quy tắc đánh version của nó.
39
+ 6. **Quyết định.** Ghi lại các lựa chọn công nghệ và cấu trúc đã được xác nhận, kèm bằng chứng
40
+ hoặc người đã xác nhận. Chỉ viết ADR khi đạt tiêu chí trong tài liệu tham chiếu về ADR;
41
+ nếu không thì một dòng trong phần tổng quan là đủ.
42
+ 7. **Sơ đồ.** Chỉ thêm sơ đồ Mermaid ở chỗ chữ khó theo dõi hơn. Giữ sơ đồ nhỏ và suy ra từ
43
+ code: mỗi node ứng với một đường dẫn thật.
44
+ 8. **Quy ước.** Ghi lại các mẫu đặt tên, phân lớp, xử lý lỗi, logging và test mà code đã theo
45
+ một cách nhất quán, mỗi mẫu kèm một đường dẫn ví dụ.
46
+ 9. **Điều chưa biết.** Đánh dấu mọi thứ chưa chứng minh được là "Unverified" và liệt kê các câu
47
+ hỏi mở kèm người có thể trả lời. Chuyển quyết định lên trên; đừng tự bịa ra.
48
+ 10. **Kiểm tra.** Xác minh link, đường dẫn và ví dụ (xem Kiểm chứng), rồi handoff kèm danh sách
49
+ bằng chứng.
50
+
51
+ ## Ràng buộc
52
+ - Chỉ mô tả những gì code, config, test hoặc quyết định đã xác nhận chứng minh được. Không
53
+ trình bày kiến trúc mong muốn như thể nó đang là hiện trạng.
54
+ - Dẫn bằng chứng bằng đường dẫn file tương đối, kèm tên symbol hoặc khoảng dòng khi hữu ích.
55
+ - Giữ tài liệu đồng bộ: một thay đổi làm đổi ranh giới hay contract phải cập nhật tài liệu của
56
+ nó trong cùng thay đổi đó. Thay đổi nội bộ nhỏ không cần ADR và thường không cần sửa tài
57
+ liệu.
58
+ - Đừng refactor code cho khớp tài liệu; hãy báo cáo chỗ lệch.
59
+ - Các role chỉ đọc (architect, reviewer) trả về phát hiện và bản văn đề xuất, không sửa file.
60
+
61
+ ## Kiểm chứng
62
+ - Mọi link tương đối và đường dẫn được dẫn đều phân giải được; chạy bộ kiểm tra link của
63
+ project nếu có, nếu không thì kiểm từng đường dẫn có tồn tại.
64
+ - Ví dụ code và câu lệnh trong tài liệu chạy hoặc biên dịch được trên cây hiện tại, hoặc được
65
+ đánh dấu là minh hoạ.
66
+ - Mỗi node và mũi nối trong sơ đồ khớp với một import, lời gọi, route hay mục config.
67
+ - Không có phát biểu nào thiếu bằng chứng hoặc thiếu dấu "Unverified".
68
+
69
+ ## Xử lý khi thất bại
70
+ - Bằng chứng xung đột (code nói một đằng, config hoặc tài liệu nói một nẻo): ghi lại cái đang
71
+ chạy, nêu xung đột thành câu hỏi mở, và báo cáo.
72
+ - Khu vực quá lớn so với việc được giao: ghi lại ranh giới và entry point, liệt kê các module
73
+ chưa phủ, rồi trả về; đừng mở rộng phạm vi.
74
+ - Cần một quyết định nhưng chưa được xác nhận: soạn ADR ở trạng thái `Proposed` và chuyển cho
75
+ main.
76
+ - Bố cục tài liệu hiện tại không rõ hoặc đang tranh cãi: hỏi trước khi cấu trúc lại.
77
+
78
+ ## Tài liệu tham chiếu
79
+ - [references/evidence-rules.md](references/evidence-rules.md) — đọc khi thu dữ kiện và dẫn nguồn (bước 2-5, 9).
80
+ - [references/adr.md](references/adr.md) — đọc khi quyết định một thay đổi có cần ADR hay không, và khi viết ADR (bước 6).
81
+ - [references/diagrams.md](references/diagrams.md) — đọc khi thêm hoặc cập nhật sơ đồ Mermaid (bước 7).
@@ -0,0 +1,62 @@
1
+ # Bản ghi quyết định kiến trúc (ADR)
2
+
3
+ Khung ADR dưới đây giữ tiêu đề tiếng ANH có chủ ý (t-d11c mục 3, người dùng quyết định
4
+ 2026-11-06): đó là hình dạng một artifact mà tooling khác đọc, không phải prose hướng dẫn cách
5
+ làm việc. Phần nội dung dưới mỗi tiêu đề viết bằng ngôn ngữ của project.
6
+
7
+ Đọc khi phán xét một thay đổi có đáng viết ADR, khi viết ADR, hoặc khi đổi status của một ADR.
8
+
9
+ ## Khi nào nên viết ADR
10
+ Viết khi có ít nhất một điều sau đúng:
11
+ - Lựa chọn đó đắt khi phải đảo ngược: nơi lưu dữ liệu, protocol, kiểu public API, runtime,
12
+ framework, mô hình triển khai.
13
+ - Nó làm đổi một ranh giới module hoặc hướng phụ thuộc được cho phép.
14
+ - Nó ảnh hưởng tới tính tương thích với bên tiêu thụ, dữ liệu đã lưu hoặc các nền tảng được hỗ
15
+ trợ.
16
+ - Đã có các phương án khác hợp lý được cân nhắc nghiêm túc rồi loại bỏ.
17
+ - Nếu không ghi lại thì cả team sẽ tranh lại chuyện đó.
18
+
19
+ Bỏ qua ADR với: refactor trong một module, cập nhật patch của dependency, chuyện đặt tên,
20
+ helper cục bộ, bản sửa lỗi đưa hành vi về đúng contract đã ghi, và các lựa chọn đã bị một ADR
21
+ hiện có quy định hoàn toàn. Một câu trong tài liệu liên quan là đủ.
22
+
23
+ ## File và cách đánh số
24
+ - Theo vị trí và cách đánh số ADR project đang dùng. Mặc định:
25
+ `docs/architecture/decisions/NNNN-short-title.md`, bốn chữ số, lấy số trống kế tiếp.
26
+ - Không bao giờ đánh số lại hay xoá một ADR; hãy thay thế nó bằng ADR mới (supersede).
27
+
28
+ ## Mẫu
29
+ ```markdown
30
+ # NNNN. Short decision title
31
+
32
+ - Status: Proposed | Accepted | Superseded by NNNN | Deprecated
33
+ - Date: YYYY-MM-DD
34
+ - Deciders: who confirmed it (role or name as the project records it)
35
+
36
+ ## Context
37
+ The forces and constraints, with evidence paths. What problem forces a choice now.
38
+
39
+ ## Decision
40
+ The choice, stated as one or two sentences in active voice.
41
+
42
+ ## Alternatives
43
+ - Option: why it was not chosen.
44
+
45
+ ## Consequences
46
+ What gets easier, what gets harder, follow-up work, and what to watch.
47
+
48
+ ## Evidence
49
+ Files, tests, benchmarks or discussions that support the context and decision.
50
+ ```
51
+
52
+ ## Vòng đời của status
53
+ | Status | Ý nghĩa | Ai chuyển |
54
+ |---|---|---|
55
+ | Proposed | Đã soạn, chưa được xác nhận | Bất kỳ người ghi; chuyển cho main để ra quyết định |
56
+ | Accepted | Đã được người sở hữu quyết định xác nhận | Main, sau khi người dùng hoặc người sở hữu có thẩm quyền xác nhận |
57
+ | Superseded by NNNN | Đã bị thay; giữ nguyên nội dung, link sang ADR mới | Người viết ADR mới |
58
+ | Deprecated | Không còn áp dụng, không có gì thay thế | Main, kèm lý do trong một ghi chú có ngày |
59
+
60
+ - Một agent không bao giờ tự đánh đề xuất của mình là Accepted khi chưa có xác nhận đó.
61
+ - Sửa một ADR đã Accepted chỉ được giới hạn ở lỗi chính tả và link; quyết định thay đổi là một
62
+ ADR mới.
@@ -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.
@@ -12,7 +12,7 @@ description: "Viết checkpoint có cấu trúc trước khi compact context c
12
12
 
13
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
14
 
15
- ## Phương pháp
15
+ ## Quy trình
16
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
17
  2. **Viết checkpoint theo đúng các mục sau** (ngắn, có ID, có giờ):
18
18
  - **Người dùng và ngôn ngữ:** profile (Phở/Cafe), ngôn ngữ trả lời.
@@ -26,7 +26,7 @@ Không compact khi đang giữ lượt (alp_wait, alp_ask, delegate wait), hoặ
26
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
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
28
 
29
- ## Kiểm tra
29
+ ## Kiểm chứng
30
30
  - Mọi assignment đang chạy đều có ID.
31
31
  - Mọi gate mở và mọi câu hỏi đang chờ đều có trong checkpoint.
32
32
  - Quyết định của người dùng được trích nguyên văn, không diễn giải.
@@ -1,6 +1,6 @@
1
1
  ---
2
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, đánh dấu 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."
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
4
  ---
5
5
 
6
6
  # Curate
@@ -11,23 +11,24 @@ description: "Rà soát toàn bộ bài học (lesson) và skill: gộp lesson t
11
11
 
12
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
13
 
14
- ## Phương pháp
14
+ ## Quy trình
15
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
16
  2. **Lập đề xuất, mỗi mục một dòng lý do:**
17
17
  - **Gộp:** các lesson cùng ý thành một rule.
18
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
19
  - **Xóa:** lesson đã được một skill bao trọn (nêu tên skill), hoặc đã lỗi thời.
20
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. Chỉ đánh dấu và nêu lý do; ALP chưa có thao tác xóa skill nên người dùng tự xóa.
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
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
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
24
  4. **Các tool:**
25
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
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`.
27
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.
28
- 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 đánh dấu; issue nào đã tạo.
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.
29
30
 
30
- ## Kiểm tra
31
+ ## Kiểm chứng
31
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.
32
33
  - Mỗi rule sau gộp vẫn giữ đủ ý của các lesson gốc.
33
34
  - Mỗi lesson bị xóa vì skill đều nêu đúng tên skill thay 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.