@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.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 (74) hide show
  1. package/README.md +248 -213
  2. package/README.vi.md +252 -186
  3. package/audit/audit.mjs +193 -10
  4. package/package.json +7 -1
  5. package/templates/README.md +30 -2
  6. package/templates/ci-laravel.yml +102 -21
  7. package/templates/ci-node.yml +61 -3
  8. package/templates/ci-python.yml +52 -3
  9. package/templates/deploy-adapter-portainer.mjs +206 -0
  10. package/templates/deploy-container-run.mjs +368 -0
  11. package/templates/deploy-container.yml +219 -0
  12. package/templates/dist-refs.yml +6 -0
  13. package/templates/docs-lint.mjs +1 -1
  14. package/templates/npx-launcher.mjs +118 -20
  15. package/templates/npx-service.mjs +828 -0
  16. package/templates/release-auto.yml +341 -32
  17. package/tools/colab +1902 -278
  18. package/tools/lib/adopt.js +373 -14
  19. package/tools/lib/branch-name.js +29 -1
  20. package/tools/lib/ci-cure.js +522 -31
  21. package/tools/lib/ci-grant.js +289 -22
  22. package/tools/lib/ci-wait.js +223 -0
  23. package/tools/lib/claim-comments.js +13 -64
  24. package/tools/lib/claim-identity.js +42 -7
  25. package/tools/lib/codec/claim.d.ts +41 -0
  26. package/tools/lib/codec/claim.js +153 -0
  27. package/tools/lib/codec/decision.d.ts +29 -0
  28. package/tools/lib/codec/decision.js +81 -0
  29. package/tools/lib/codec/grants.d.ts +82 -0
  30. package/tools/lib/codec/grants.js +268 -0
  31. package/tools/lib/codec/hold.d.ts +26 -0
  32. package/tools/lib/codec/hold.js +152 -0
  33. package/tools/lib/codec/index.d.ts +21 -0
  34. package/tools/lib/codec/index.js +32 -0
  35. package/tools/lib/codec/labels.d.ts +65 -0
  36. package/tools/lib/codec/labels.js +723 -0
  37. package/tools/lib/codec/markers.d.ts +35 -0
  38. package/tools/lib/codec/markers.js +138 -0
  39. package/tools/lib/codec/release.d.ts +17 -0
  40. package/tools/lib/codec/release.js +69 -0
  41. package/tools/lib/codec/samples.json +778 -0
  42. package/tools/lib/codeowners.js +68 -4
  43. package/tools/lib/container-close.js +38 -0
  44. package/tools/lib/cure-diff.js +198 -9
  45. package/tools/lib/decision-record.js +15 -39
  46. package/tools/lib/docs-only.js +15 -1
  47. package/tools/lib/exposure-shape.js +42 -8
  48. package/tools/lib/git.js +324 -42
  49. package/tools/lib/group-labels.js +65 -0
  50. package/tools/lib/install-check.js +14 -8
  51. package/tools/lib/install-route.js +139 -0
  52. package/tools/lib/instruction-file.js +1 -0
  53. package/tools/lib/labels.js +22 -647
  54. package/tools/lib/local-adopt.js +8 -4
  55. package/tools/lib/migration-grant.js +206 -104
  56. package/tools/lib/place.js +2 -2
  57. package/tools/lib/release-cut.js +199 -25
  58. package/tools/lib/release-finalize.js +111 -23
  59. package/tools/lib/release-policy.js +130 -22
  60. package/tools/lib/release-runner.js +125 -0
  61. package/tools/lib/release-tag.js +3 -1
  62. package/tools/lib/scratch-dirs.js +118 -0
  63. package/tools/lib/ship-batch.js +36 -1
  64. package/tools/lib/ship-human-door.js +76 -0
  65. package/tools/lib/stamp.js +7 -0
  66. package/tools/lib/tracker-fake.js +195 -0
  67. package/tools/lib/tracker-github.js +106 -0
  68. package/tools/lib/tracker-scenarios.json +206 -0
  69. package/tools/lib/tracker.js +64 -0
  70. package/tools/lib/tree-green.js +88 -0
  71. package/tools/lib/util.js +17 -1
  72. package/tools/lib/verify-runs.js +104 -0
  73. package/tools/lib/wake.js +8 -90
  74. package/tools/lib/workflow-triggers.js +48 -0
package/README.vi.md CHANGED
@@ -8,11 +8,27 @@ người thật lẫn AI agent — mà không giẫm chân nhau.
8
8
  **Nếu bạn là AI agent, dừng ở đây và đọc [`CLAUDE.md`](CLAUDE.md).**
9
9
  File này dành cho con người.
10
10
 
11
- *(Tài liệu chuẩn tắc — [`CONVENTIONS.md`](CONVENTIONS.md) — viết bằng tiếng Anh
12
- để agent và tool đọc được. Bản này là cửa vào tiếng Việt cho anh em dev; bản
13
- tiếng Anh nằm ở [`README.md`](README.md). Cả hai chỉ là cửa vào, không phải
14
- tài liệu chuẩn tắc — khi hai bản nói khác nhau thì **cả hai đều sai** cho tới
15
- khi khớp lại với `CONVENTIONS.md`.)*
11
+ ## Bắt đầu nhanh
12
+
13
+ ```sh
14
+ git clone https://github.com/futurelastic/colab-handbook.git ~/code/colab-handbook
15
+ cd ~/code/colab-handbook && ./install.sh --all # skills + CLI colab + hook, từ bản phát hành mới nhất; --dry để xem trước
16
+ cd /duong-dan/toi/repo-cua-ban
17
+ colab adopt # chỉ hỏi những gì không tự dò ra được, rồi ghi .github/project.yml
18
+ colab labels --ensure # tạo các label quy ước
19
+ colab register # đưa repo vào danh sách fleet của máy này
20
+ ```
21
+
22
+ Sau đó, trong một phiên agent ở repo đó, chạy `/code-start <số-issue>`. Có agent
23
+ trong tay thì `/handbook-sync` thay được ba lệnh cuối và làm nốt phần adopt còn
24
+ lại (xem [*Adopt vào một repo*](#adopt-vào-một-repo)). Cần có `git`, `node` ≥ 18
25
+ và `gh` ≥ 2.94 đã đăng nhập (`gh auth login`); gói `gh` của các distro thường cũ
26
+ hơn, nên hãy cài từ [cli.github.com](https://cli.github.com).
27
+
28
+ *([`CONVENTIONS.md`](CONVENTIONS.md) là tài liệu chuẩn tắc, viết bằng tiếng Anh
29
+ để agent và tool đọc được. File này và bản tiếng Anh [`README.md`](README.md)
30
+ chỉ là cửa vào. Khi hai bản nói khác nhau thì **cả hai đều sai** cho tới khi
31
+ khớp lại với `CONVENTIONS.md`.)*
16
32
 
17
33
  ## Đây là cái gì
18
34
 
@@ -21,10 +37,10 @@ merge vào đâu, release là gì, báo "tôi đang làm việc này" bằng cá
21
37
  tình để **cách hiện thực** (phiên bản Node, test runner, file CI của bạn) cho
22
38
  từng repo tự quyết.
23
39
 
24
- Mọi thứ trong đây được chưng cất từ việc vận hành ~25 repo thật, trong đó có
25
- nhiều app production được bảo trì gần như hoàn toàn bởi AI agent chạy song song
26
- trên nhiều worktree. Mục anti-pattern không phải lý thuyết: từng mục là chuyện
27
- đã xảy ra thật, kèm sẹo để chứng minh.
40
+ Nó được chưng cất từ việc vận hành một fleet repo thật, trong đó có nhiều app
41
+ production được bảo trì gần như hoàn toàn bởi AI agent chạy song song trên nhiều
42
+ worktree. Mục anti-pattern không phải lý thuyết: từng mục là chuyện đã xảy ra
43
+ thật.
28
44
 
29
45
  ### Nó giải quyết vấn đề gì
30
46
 
@@ -48,19 +64,17 @@ sự thật về một repo lại nằm trong trí nhớ của ai đó thay vì
48
64
 
49
65
  ### Thực chất nó làm gì
50
66
 
51
- Nó bắt mỗi repo tự trả lời một nhúm câu hỏi về chính mình, **một lần**, vào một
52
- file mà mọi phiên đều đọc trước khi động vào bất cứ thứ gì — hôm nay đã có
53
- production chưa, còn ai khác làm ở đây, merge sai thì hỏng cái gì, mỗi lúc chạy
54
- bao nhiêu đầu việc, và code đi tới chỗ nó chạy bằng đường nào.
55
-
56
- Mọi thứ còn lại suy ra từ mấy câu trả lời đó: merge vào nhánh nào, ở repo này
57
- release nghĩa là gì, có bắt buộc phải có nhánh không, một phiên phải ghi lại
58
- bao nhiêu trước khi dừng. Phiên làm việc không phải đoán, và hai repo không bao
59
- giờ hiểu khác nhau về cùng một từ.
67
+ Nó bắt mỗi repo tự trả lời năm câu hỏi về chính mình, **một lần**, vào một file
68
+ mà mọi phiên đều đọc trước khi động vào bất cứ thứ gì (xem [*Năm câu
69
+ hỏi*](#năm-câu-hỏi)). Mọi thứ còn lại suy ra từ mấy câu trả lời đó: merge vào
70
+ nhánh nào, ở repo này release nghĩa là gì, có bắt buộc phải có nhánh không, một
71
+ phiên phải ghi lại bao nhiêu trước khi dừng.
60
72
 
61
- Phần còn lại của repo sinh ra để phục vụ điều đó: một CLI làm giúp phần cơ học,
62
- một audit báo chỗ nào thực tế đã trôi khỏi thứ repo tự khai, và các luồng phiên
63
- làm việc mang đi được để phiên code ở đâu cũng mở ra và đóng lại giống nhau.
73
+ Phần còn lại của repo phục vụ điều đó: một CLI làm giúp phần cơ học, một audit
74
+ báo chỗ nào thực tế đã trôi khỏi thứ repo tự khai, và các luồng phiên làm việc
75
+ (skill) để phiên code ở đâu cũng mở ra và đóng lại giống nhau. Skill chỉ là văn
76
+ xuôi — một người ngồi terminal có thể làm theo mà không cần agent hay tool nào
77
+ khác.
64
78
 
65
79
  ### Nó không phải cái gì
66
80
 
@@ -70,49 +84,154 @@ làm việc mang đi được để phiên code ở đâu cũng mở ra và đó
70
84
  - **Không phải hệ thống CI, cũng không có ý kiến gì về stack của bạn.** Ngôn
71
85
  ngữ, test runner, pipeline — của bạn cả. Handbook chỉ yêu cầu pipeline cho ra
72
86
  hai kết quả, và không bao giờ nói phải làm bằng cách nào.
73
- - **Không phải lớp ép buộc**, trừ đúng một ngoại lệ cố ý. Chuyện tuân thủ chỉ là
74
- cảnh báo, vì sai một quy ước thì tốn một cuộc trao đổi. Chuyện phát hành ra
75
- ngoài thì chặn, vì history không thu hồi lại được một khi đã có người clone.
87
+ - **Phần lớn không phải lớp ép buộc.** Chuyện tuân thủ chỉ là cảnh báo. Vài thứ
88
+ ít ỏi thật sự chặn được liệt kê ở [*Vì sao ép buộc ít
89
+ vậy*](#vì-sao-ép-buộc-ít-vậy).
76
90
  - **Không phải thang đo độ trưởng thành.** Không câu trả lời nào ở đây xếp repo
77
91
  này trên repo kia. Một repo chưa có production không phải repo tệ hơn; nó là
78
92
  repo có ít cổng hơn.
79
93
 
80
- Nếu bạn làm một repo một mình, đọc mục anti-pattern rồi lấy cái nào thấy dùng
81
- được. Còn nếu bạn chạy nhiều repo — hoặc bạn làm việc cùng những agent chưa
82
- từng gặp người đặt ra luật — thì nhiều khả năng nó hoàn vốn nhanh hơn cả thời
83
- gian bạn bỏ ra để đọc.
94
+ ## Phiên làm việc đầu tiên
95
+
96
+ Mỗi đầu việc đi qua một vòng. Mỗi bước là một skill, gọi trong phiên agent bằng
97
+ slash command (`/code-start 42`), hoặc tự làm theo bằng tay từ
98
+ [`skills/`](skills/).
99
+
100
+ | Bước | Skill | Ai chạy | Để lại gì |
101
+ |---|---|---|---|
102
+ | 1. Chọn | `/code-triage` | điều phối | việc sẵn sàng theo thứ tự, label `group:` trên các issue phải chung một nhánh, `needs-plan` trên việc khó, lệnh để bắt đầu |
103
+ | 2. Mở | `/code-start <N>` | thợ | issue đã claim, nhánh cắt từ trunk và đã push, một worktree, một file plan ngắn |
104
+ | 3. Làm | — | thợ | commit trên nhánh |
105
+ | 4. Bàn giao | `/code-wrap` | thợ | điều học được ghi lên Issue, gate của repo đã chạy, nhánh đã push — rồi **dừng** |
106
+ | 5. Merge | `/code-ship` | điều phối, sau khi người đồng ý | một squash commit trên trunk kèm `Closes #N`, bằng chứng trên từng issue, claim đã nhả, worktree đã gỡ |
107
+ | 6. Dọn | `/code-sweep` | điều phối | việc đã xong được ship, claim và worktree cũ được dọn |
108
+ | 7. Release | release workflow, hoặc `/release-rung` | tự động, hoặc người khi tag là thứ deploy | một tag ứng viên, rồi bản final sau thời gian thử — chỉ khi `exposure` của repo có release |
109
+
110
+ Cũng trong [`skills/`](skills/): `code-plan` (plan đầy đủ cho issue khó, do
111
+ `code-start` gọi khi có cờ), `handbook-sync` (kéo một repo lên bản handbook mới
112
+ nhất), và `migration-review` (review migration của một nhánh, cho người/agent
113
+ được repo gán vai đó).
114
+
115
+ **Tự chạy vòng này bằng tay ở terminal?** Không có `--session` thì `colab` đặt
116
+ tên bạn là `person:<git user.email>/<host token>`, nên claim và bằng chứng ship
117
+ đều ghi rõ ai làm. Nếu làm nhiều đơn vị việc cùng lúc ở các shell khác nhau,
118
+ đặt cho mỗi shell một `COLAB_SESSION=<id ổn định bất kỳ>` để các hold không lẫn
119
+ vào nhau.
120
+
121
+ **Mấy từ sẽ gặp:**
122
+
123
+ - **Trunk** — nhánh các phiên merge vào (`trunk:` trong `project.yml`).
124
+ **Promotion** — merge trunk vào `main` khi trunk không phải `main`; ở repo
125
+ `live` thì chính cú promote *là* deploy.
126
+ - **Claim** — assignee + label `in-progress`, có nhánh đã push lên remote làm
127
+ bằng, lấy *trước khi* bắt tay vào làm.
128
+ - **Thợ / điều phối** (implementer / coordinator) — phiên viết code / phiên
129
+ chọn việc, merge và dọn dẹp. Một người có thể làm cả hai, ở hai thời điểm.
130
+ - **Phase A / Phase B** — `code-wrap` (nửa của thợ, dừng trước mọi cú merge) /
131
+ `code-ship` (nửa của điều phối: cú merge và mọi thứ sau đó).
132
+ - **Nấc (rung)** — phiên viết bao nhiêu plan: 0 không viết, 1 một khung năm
133
+ dòng, 2 plan đầy đủ từ `code-plan`.
134
+
135
+ Người mới: đọc [`CONVENTIONS.md` §1](CONVENTIONS.md#1-the-model-in-one-picture)
136
+ (mô hình) và [§11](CONVENTIONS.md#11-quick-reference) (tra nhanh) trước. Phần
137
+ còn lại của `CONVENTIONS.md` là tài liệu tra cứu — cần gì tra nấy, đừng đọc từ
138
+ đầu tới cuối.
84
139
 
85
140
  ## Năm câu hỏi
86
141
 
87
- Adopt handbook này nghĩa là trả lời năm câu hỏi về repo của bạn, một lần, ghi
88
- vào `.github/project.yml` — để không phiên nào phải đoán, và không hai repo
89
- nào hiểu khác nhau về cùng một từ:
90
-
91
- 1. **Hôm nay đã có đích deploy chưa** — và đến đó bằng đường nào: một tag gác
92
- cổng production, chính cú promote là deploy, một người chạy runbook bằng
93
- tay, hay chưa có gì sống cả?
94
- 2. **Còn ai khác làm ở repo này** — một mình, một team, hay có cả người
95
- ngoài?
96
- 3. **Merge nhầm thì cái gì hỏng** — không gì cả, chỉ những người đang có mặt
97
- ở đây, người dùng qua lần promote kế tiếp, hay người dùng/người adopt qua
98
- một artifact đã phát hành?
99
- 4. **Một việc tại một thời điểm, hay nhiều việc chạy song song?**
100
- 5. **Code đi tới chỗ nó chạy bằng đường nào** — một workflow CI, một git
101
- hook, một quy trình tay có ghi lại, một checkout đang sống sẵn, một
102
- artifact phát hành, dữ liệu của hệ thống khác, hay chưa có đường nào cả?
103
-
104
- Trả lời xong năm câu này là quyết định luôn mọi thứ còn lại: merge vào nhánh
105
- nào, release nghĩa là gì, Issue tường thuật nhiều hay ít, cần gì để undo một
106
- merge, có bắt buộc phải có branch hay không. Không câu nào bị hỏi hai lần, và
107
- không câu nào hỏi cái mà repo đã tự nói sẵn rồi — nhánh mặc định, toolchain,
108
- port của nó.
109
-
110
- Issue được **claim** bằng assignee + label `in-progress` trước khi bắt tay vào
111
- làm, nên các phiên song song không bao giờ đụng nhau trên cùng một việc.
112
-
113
- Toàn bộ luật — mỗi câu trả lời quy về đâu, và vì sao:
114
- [`CONVENTIONS.md`](CONVENTIONS.md). Đọc mất ~15 phút và là file **chuẩn tắc
115
- duy nhất** — mọi thứ còn lại trong repo chỉ phục vụ nó.
142
+ Adopt nghĩa là trả lời mấy câu này về repo của bạn vào `.github/project.yml`.
143
+ `colab adopt` chỉ hỏi hai câu làm thay đổi cổng (1 và 3), dưới dạng menu đánh
144
+ số; ba câu còn lại là tuỳ chọn, trả lời lúc nào sau này cũng được:
145
+
146
+ | # | Câu hỏi | Ghi vào | Lúc adopt |
147
+ |---|---|---|---|
148
+ | 1 | **Hôm nay** (chứ không phải "sắp") đã có đích deploy chưa, và đến đó bằng đường nào — một tag, chính cú promote, một người chạy runbook, hay chưa có gì? | `production` + `deploy` | có hỏi |
149
+ | 2 | Còn ai khác làm ở đây — một mình bạn, một team, hay có cả người ngoài? | `room` | tuỳ chọn — `colab adopt --axis room` |
150
+ | 3 | Merge nhầm thì cái gì hỏng — không gì cả, chỉ những người đang có mặt, người dùng qua lần promote kế tiếp, hay người dùng/người adopt qua một artifact đã phát hành? | `exposure` | có hỏi — người thật trả lời |
151
+ | 4 | Một người có được commit thẳng vào trunk song song với các phiên worktree không — tự do, có khai ý định, hay không bao giờ? | `writes` | tuỳ chọn — `colab adopt --axis writes` |
152
+ | 5 | Code đi tới chỗ nó chạy bằng đường nào — một workflow CI, một git hook, một quy trình tay có ghi lại, một checkout đang sống, một artifact phát hành, dữ liệu của hệ thống khác, hay chưa có đường nào? | `channels` | tuỳ chọn — `colab adopt --axis channels` |
153
+
154
+ **Trả lời câu 3 là việc của người thật** khi câu trả lời là "không gì cả" hoặc
155
+ "chỉ những người đang có mặt". Agent làm được mọi phần còn lại; tới bước đó,
156
+ `colab adopt` in ra, ngay dòng đầu tiên, đúng một lệnh để người thật chạy.
157
+
158
+ Không câu nào hỏi cái repo đã tự nói sẵn — nhánh mặc định (`trunk`, giữ nguyên
159
+ như đang có: nhánh mặc định tên `master` vẫn hợp lệ, không cần đổi tên), toolchain,
160
+ port đều được tự dò. Số cổng, nghi thức release và việc có bắt buộc phải có
161
+ nhánh hay không đều suy ra từ câu trả lời. Mỗi câu trả lời quy về đâu, và vì
162
+ sao: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) và
163
+ [§9](CONVENTIONS.md#9-adopting-this); từng field:
164
+ [`project.schema.md`](project.schema.md).
165
+
166
+ ## Adopt vào một repo
167
+
168
+ **Đường mặc định: chạy `/handbook-sync` trong một phiên agent ngay trong repo
169
+ đó.** Nó nhận ra repo chưa adopt gì và đi hết đường adopt — descriptor (qua
170
+ `colab adopt`), label, block `CLAUDE.md`, CI từ template, và đăng ký trên máy
171
+ này. Chạy lại về sau, chính skill đó kéo một repo đã adopt lên bản handbook mới
172
+ nhất mà không làm mất phần bạn đã sửa.
173
+
174
+ Làm bằng tay thì cũng đúng các bước đó (checklist đầy đủ:
175
+ [`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this)):
176
+
177
+ 1. `colab adopt` — trả lời hai câu hỏi về cổng và ghi `.github/project.yml`. Nó dừng ở
178
+ đó và in ra các bước còn lại.
179
+ 2. `colab labels --ensure` — các label quy ước không có sẵn. Một check mà label
180
+ của nó chưa từng được tạo thì không bao giờ chạy được.
181
+ 3. Dán [`templates/repo-CLAUDE-block.md`](templates/repo-CLAUDE-block.md) vào
182
+ `CLAUDE.md` của repo — đây là cách agent phát hiện ra bộ quy ước.
183
+ 4. Đảm bảo CI đạt hai kết quả bắt buộc: quét secret và build, với phiên bản
184
+ toolchain **resolve từ manifest của chính repo**, không bao giờ hardcode.
185
+ Copy template từ [`templates/`](templates/) nếu thấy tiện.
186
+ 5. `colab register` — đưa repo vào danh sách fleet của máy này, để cả audit lẫn
187
+ bộ cấp port đều biết tới nó.
188
+
189
+ Mấy flag của `colab adopt` nên biết:
190
+
191
+ - `--autonomy auto-trunk` — ghi lại quyền maintainer cấp cho agent tự hoàn tất
192
+ cú merge vào trunk qua `colab ship` (không bao giờ là release). Cần người.
193
+ - `--land` — commit những gì lần chạy này ghi thẳng vào trunk rồi push, để
194
+ nhánh feature đầu tiên được xét theo luật mới. Cần người (`COLAB_HUMAN=1`
195
+ kèm `--answered-by`).
196
+ - `--fork` — repo bám theo một upstream không phải của bạn (tự dò khi có remote
197
+ tên `upstream`); khi đó block `CLAUDE.md` chỉ được nối thêm, không bị cấu trúc
198
+ lại, và workflow agent riêng của upstream được nêu tên.
199
+ - `--local` — bạn hoàn toàn không commit được vào repo này; mọi thứ nằm trong
200
+ bản clone của bạn ([*Working in a repo you don't
201
+ own*](CONVENTIONS.md#working-in-a-repo-you-dont-own)).
202
+
203
+ Nhánh có sẵn từ trước được **giữ nguyên** (grandfathered). Đừng đổi tên gì cả.
204
+
205
+ ## Tuỳ biến một skill cho repo của bạn
206
+
207
+ Muốn một skill chạy khác đi ở một repo — comment Issue bằng tiếng Nhật, thêm
208
+ một bước kiểm tra trước wrap? Đừng fork skill: bản fork không còn nhận cập nhật
209
+ từ handbook. Hãy viết phần khác biệt vào `.colab/skills/<skill>.md` (ví dụ
210
+ `.colab/skills/code-wrap.md`), bằng văn xuôi thường. Mỗi skill đọc file đó
211
+ trước các bước của chính nó, và nội dung file thắng phần chữ của skill trong
212
+ repo đó. Nó không bao giờ nới một cổng của `colab`: claim hay merge đã bị từ
213
+ chối thì vẫn bị từ chối. Hãy gọi bước bạn muốn chỉnh theo số của nó (`code-ship`
214
+ B1c, `code-sweep` §3): một skill lớn gồm một phần lõi ngắn cộng các file tham
215
+ chiếu, và phần lõi giữ số của mọi bước.
216
+
217
+ Claude Code tự nạp file vào skill. Các engine khác có một câu thường trong mỗi
218
+ skill bảo agent đọc file, cách này chạy được mà không cần engine hỗ trợ gì.
219
+ Vì file này ra lệnh cho agent, thay đổi trong nó không bao giờ được coi là
220
+ docs-only: nó merge bằng `auto-trunk` hoặc khi có người duyệt, giống một thay đổi
221
+ `CLAUDE.md`. Quy tắc:
222
+ [`CONVENTIONS.md` §8, *Local policy*](CONVENTIONS.md#local-policy--a-repo-refines-a-skill-without-forking-it-520).
223
+
224
+ ## Tự động hoá tùy chọn, đặt lên trên
225
+
226
+ Không có gì ở đây giả định đã có dashboard, scheduler hay bot. Người adopt vẫn
227
+ có thể tự dựng: mở phiên từ một nút bấm, chạy vòng làm việc theo lịch, coi cú
228
+ bấm nút merge của một người là cái gật đầu mà `code-ship` đang chờ, hay đẩy
229
+ thông báo khi việc đổi trạng thái. Tool như vậy đọc đúng những artefact chung mà
230
+ con người đọc — `.github/project.yml`, label, claim trên từng Issue, file
231
+ `~/.colab/state.json` trên máy — và có thể nhận event của `colab` ở `notifyUrl`
232
+ ([`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default)).
233
+ Nó không bao giờ thay đổi một cổng của `colab`: cái gật đầu trước khi merge và
234
+ quyền cấp trước khi chạy migration vẫn đứng vững dù có nó hay không.
116
235
 
117
236
  ## Cấu trúc repo
118
237
 
@@ -121,153 +240,100 @@ duy nhất** — mọi thứ còn lại trong repo chỉ phục vụ nó.
121
240
  | [`CONVENTIONS.md`](CONVENTIONS.md) | Luật. Chuẩn tắc, nguồn sự thật duy nhất (EN). |
122
241
  | [`CLAUDE.md`](CLAUDE.md) | Cửa vào cho AI agent — bản chưng cất vận hành (EN). |
123
242
  | [`project.schema.md`](project.schema.md) | Tham chiếu field của `.github/project.yml`. |
124
- | [`templates/`](templates/) | Điểm khởi đầu **copy-về-là-của-bạn**: CI, release, git hook (một bản quét secret và một bản quét danh tính), và block `CLAUDE.md` cho repo adopt. **Không có gì được gọi từ xa** — copy, sửa, sở hữu. Là template chứ không phải scaffold, vì scaffold chỉ tới được những repo tạo ra sau khi nó ra đời. |
125
- | [`tools/`](tools/) | `colab` — một CLI nhỏ (tùy chọn): adopt một repo, claim issue, cấp port, quản lý worktree, và merge nhánh đã xong vào trunk khi repo cho phép. State JSON, không dependency. Tham chiếu đầy đủ các lệnh: [`tools/README.md`](tools/README.md). |
126
- | [`audit/`](audit/) | Trình kiểm tra conformance từ bên ngoài. Đọc mọi repo của bạn — mọi owner, kể cả repo local-only — và báo drift trong một lần chạy. Chỉ cảnh báo, không bao giờ chặn. Thêm `--identity` thì quét cả description và topic của repo public — thứ mà không git hook nào nhìn thấy được. Ý nghĩa từng check: [`audit/README.md`](audit/README.md). |
127
- | [`skills/`](skills/) | Flow phiên làm việc portable: `code-triage` (chọn việc tiếp theo, gắn cờ việc khó cần plan) → `code-start` (mở phiên; chạy `code-plan` khi có cờ) → `code-wrap` (chưng cất + gate + bàn giao) → `code-ship` (chấm điểm + merge, cần người xác nhận), cộng `code-sweep` (dọn sạch mọi việc ĐÃ XONG trong một repo — hoặc chỉ một nhóm issue hay một phiên được chỉ định — chạy `code-wrap`+`code-ship` từng cái) `handbook-sync` (kéo MỘT repo lên bản handbook mới nhất, chạy từ trong repo đó), và `release-rung` (đường dự phòng thủ công và phần giải thích cho release workflow — workflow mới là thứ tự chạy: đi hết nấc release của một repo từ phiên điều phối — candidate, thời gian thử, quyền phủ quyết `release-hold`, bản final — qua `colab release cut`/`finalize`, không bao giờ tag tay), và `migration-review` (cho người/agent mà repo gán vai migration-reviewer: review migration của một nhánh theo engine deploy thật và chốt đúng một verdict — GRANT kèm review record, REWORK kèm brief sửa, hoặc ESCALATE lên người — kèm bộ test mù phải chạy trước khi gán reviewer mới). [`install.sh`](install.sh) cài chúng thành skill Claude Code — xem mục *Cài đặt máy* ngay dưới. |
128
- | [`install.sh`](install.sh) | Cài đặt cho **máy của bạn**: skills, CLI `colab`, hook pre-commit, danh sách repo cho audit. Idempotent, và `--dry` cho xem trước mọi thứ. |
129
-
130
- ## Cài CLI từ npm
131
-
132
- CLI `colab` còn được phát hành dạng package npm công khai **`@futurelastic/colab-handbook`**. Lệnh bạn gõ vẫn là `colab`.
133
-
134
- ```sh
135
- npx @futurelastic/colab-handbook <lệnh> # chạy một lần, không cài gì, không cần tài khoản npm
136
- npm i -g @futurelastic/colab-handbook # rồi: colab <lệnh>
137
- npm i -g @futurelastic/colab-handbook@next # bản ứng viên (vX.Y.Z-rc.N) thay vì bản final
138
- ```
139
-
140
- Package chỉ chứa những gì `colab` đọc lúc chạy — CLI, `lib/`, `templates/` và `audit/audit.mjs` — không gì khác; `colab template` và `colab adopt` chạy được từ bản trên registry và đóng dấu đúng version của package. Các skill **không** nằm trong đó: chúng cài bằng `./install.sh` từ một bản clone (xem bên dưới), vì phải symlink vào `~/.claude/skills/`. Mỗi tarball được CI đối chiếu từng file với allowlist (`scripts/check-pack-allowlist.mjs`).
243
+ | [`templates/`](templates/) | Điểm khởi đầu **copy-về-là-của-bạn**: CI, release, git hook (một bản quét secret và một bản quét danh tính), và block `CLAUDE.md` cho repo adopt. Không có gì được gọi từ xa — copy, sửa, sở hữu. |
244
+ | [`tools/`](tools/) | `colab` — một CLI nhỏ (tùy chọn): adopt một repo, claim issue, cấp port, quản lý worktree, và merge nhánh đã xong vào trunk khi repo cho phép. State JSON, không dependency. Tham chiếu các lệnh: [`tools/README.md`](tools/README.md). |
245
+ | [`audit/`](audit/) | Trình kiểm tra conformance từ bên ngoài. Đọc mọi repo của bạn — mọi owner, kể cả repo local-only — và báo drift trong một lần chạy. Chỉ cảnh báo. Thêm `--identity` thì quét cả description và topic của repo public — thứ mà không git hook nào nhìn thấy được. Ý nghĩa từng check: [`audit/README.md`](audit/README.md). |
246
+ | [`skills/`](skills/) | Luồng phiên làm việc — xem [*Phiên làm việc đầu tiên*](#phiên-làm-việc-đầu-tiên). `install.sh` cài chúng thành skill Claude Code. |
247
+ | [`install.sh`](install.sh) | Cài đặt cho **máy của bạn**: skills, CLI `colab`, hook pre-commit, danh sách fleet. Idempotent; `--dry` cho xem trước mọi thứ. |
141
248
 
142
249
  ## Cài đặt máy
143
250
 
144
- Làm một lần cho mỗi máy, trước khi adopt handbook vào repo nào.
251
+ Làm một lần cho mỗi máy. Clone vào chỗ ở lâu dài — các skill là symlink trỏ
252
+ *thẳng vào working tree này*, nên repo đang checkout cái gì thì mọi phiên dùng
253
+ đúng bản skill đó. `install.sh` kiểm tra đủ điều kiện trước khi đụng vào gì,
254
+ không bao giờ ghi đè thứ nó không tạo ra, và `--dry` in kế hoạch ra trước.
145
255
 
146
- **Cần có sẵn:** `git`; `node` ≥ 18 (`.nvmrc` ghim 22 — đúng bản CI ở đây chạy);
147
- `gh` và phải **đăng nhập rồi** (`gh auth login`) — claim issue, các skill và
148
- phần audit repo remote đều vô dụng nếu thiếu, mà lỗi thì mãi về sau mới hiện ra
149
- dưới dạng khó hiểu; `gitleaks` chỉ cần nếu bạn muốn bật hook pre-commit.
150
- `install.sh` kiểm tra hết những thứ này và báo cái nào thiếu *trước khi* đụng
151
- vào bất cứ gì.
256
+ **Bạn nhận phiên bản nào.** `main` chạy trước bản phát hành chính thức cuối
257
+ cùng, nên lần cài đầu tiên từ một bản clone mới sẽ checkout **tag phát hành
258
+ chính thức mới nhất** (`vX.Y.Z`, không bao giờ là bản ứng viên) rồi cài từ đó —
259
+ giống mặc định của npm. Muốn theo `main`, kể cả phần chưa phát hành, thì chạy
260
+ lần cài đầu với `--trunk`. Lần chạy nào cũng in ra bạn đang ở bản nào. Đổi về
261
+ sau đều phải chủ động:
152
262
 
153
- **1. Clone vào chỗ ở lâu dài** — để chung với đống code của bạn, đừng để trong
154
- thư mục tạm.
263
+ - lên bản phát hành mới hơn: `./install.sh --release`;
264
+ - từ một bản phát hành quay về `main`: `git checkout main && ./install.sh --trunk`
265
+ (installer của bản phát hành cũ không biết `--trunk`, nên checkout `main` trước).
155
266
 
156
- ```sh
157
- git clone https://github.com/futurelastic/colab-handbook.git ~/code/colab-handbook
158
- cd ~/code/colab-handbook
159
- ```
160
-
161
- **Bản clone này là hạ tầng, không phải file tải về xem cho biết.** Các skill
162
- được cài bằng symlink trỏ *thẳng vào working tree này*: xoá clone đi là mọi
163
- phiên trên máy mất skill, và repo đang checkout nhánh nào thì mọi phiên dùng
164
- đúng bản skill của nhánh đó. Nên khi không trực tiếp sửa handbook, hãy để nó ở
165
- `main`. `install.sh` sẽ cảnh báo nếu thấy mình đang nằm trong `/tmp`,
166
- `~/Downloads` hay `~/Desktop`.
167
-
168
- **2. Cài.**
169
-
170
- ```sh
171
- ./install.sh --all --dry # xem trước sẽ làm gì; không thay đổi gì cả
172
- ./install.sh --all # skills + CLI colab + hook pre-commit + danh sách repo
173
- ```
174
-
175
- `--all` là lựa chọn nên dùng cho lần chạy đầu. Mọi thứ nó làm đều là symlink
176
- hoặc copy, chạy lại bao nhiêu lần cũng được, và không bao giờ ghi đè thứ nó
177
- không tạo ra — skill của riêng bạn, hay `~/.colab/repos.txt` đã có sẵn, đều được
178
- giữ nguyên kèm một dòng cảnh báo. Chạy trơn `./install.sh` thì chỉ cài skills,
179
- nếu bạn thật sự chỉ cần bấy nhiêu.
267
+ Clone đang có thay đổi chưa commit thì không bao giờ bị chuyển, và chạy lại
268
+ không kèm flag nào thì giữ nguyên thứ đang checkout.
180
269
 
181
270
  | Flag | Làm gì |
182
271
  |---|---|
183
272
  | *(không có)* | Symlink `skills/` vào `~/.claude/skills/`, để mở repo nào cũng có. |
184
- | `--tools` | Cài một CLI theo hai cách: một **symlink** ở `~/.local/bin/colab` cho các phiên làm việc của bạn (có kiểm tra thư mục đó thật sự nằm trong `PATH` không, thiếu thì in ra đúng dòng cần thêm), cộng một **bản đóng băng** có đóng dấu ở `~/.colab/bin/colab` cho các service luôn-bật — xem ngay dưới. |
185
- | `--hooks` | Trỏ git của clone này vào `.githooks/`, ở đó `pre-commit` chạy lần lượt mọi check trong `pre-commit.d/` — quét secret bằng gitleaks, và quét danh tính (identity) vốn cần một danh sách từ khoá do bạn cấp bằng đường dẫn và giữ NGOÀI mọi repo (xem [`templates/README.md`](templates/README.md)). `core.hooksPath` nằm trong `.git/config` nên là cấu hình per-clone, per-máy, không đi theo repo. |
186
- | `--fleet` | Tạo `~/.colab/repos.txt` từ `audit/repos.txt`, chỉ khi file chưa tồn tại. Danh sách đó cố tình nằm ngoài repo: nó ghi tên các repo private của bạn, còn repo này thì public. |
273
+ | `--tools` | CLI `colab` cài hai lần: một **symlink** ở `~/.local/bin/colab` cho các phiên làm việc của bạn (in sẵn dòng `PATH` nếu cần), và một **bản đóng băng** có đóng dấu ở `~/.colab/bin/colab` cho các service luôn-bật. Đồng thời tạo `~/.colab/state.json` rỗng nếu chưa có. |
274
+ | `--hooks` | Trỏ git của clone này vào `.githooks/`: quét secret bằng gitleaks, và quét danh tính với danh sách từ khoá do bạn giữ NGOÀI mọi repo (xem [`templates/README.md`](templates/README.md)). |
275
+ | `--fleet` | Tạo `~/.colab/repos.txt` chỉ chứa ghi chú định dạng, nếu chưa có. Nó cố tình nằm trên máy vì nó ghi tên các repo private của bạn; `colab register` mới là thứ điền vào. |
187
276
  | `--all` | `--tools --hooks --fleet`. |
188
- | `--notify-url <url>` | Ghi `notifyUrl` vào `~/.colab/config.json` bằng URL nhận event của một observer chạy trên máy, chỉ khi khoá đó chưa có — giá trị đang có không bao giờ bị ghi đè. Không truyền flag thì `--tools` lấy URL từ `~/.colab/notify-endpoint` nếu observer trên máy đã khai ở đó; không có thì in rõ `notifyUrl` đang trống và sẽ mất những event nào. Xem [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
189
- | `--dry` | In ra sẽ làm gì, không thay đổi gì. Ghép được với mọi flag trên. |
190
-
191
- **Service luôn-bật phải gọi `~/.colab/bin/colab`.** Bản CLI symlink chạy theo
192
- đúng nhánh mà clone này đang checkout — với một phiên làm việc của con người thì
193
- đó là chủ đích, nhưng với thứ sống lâu hơn một phiên thì đó là sai. Một daemon,
194
- một launch agent hay một runner headless bật từ mấy tháng trước sẽ âm thầm đổi
195
- hành vi chỉ vì ai đó checkout một nhánh chẳng liên quan, mà không có gì báo cả:
196
- tiến trình vẫn chạy, chỉ là chạy khác đi. Nên `--tools` còn ghi thêm một **bản
197
- copy** vào `~/.colab/bin/` (có tôn trọng `COLAB_HOME`), đóng dấu version handbook
198
- mà nó được lấy ra — hoặc, khi cây làm việc đó đang đi trước tag gần nhất, đóng dấu
199
- đúng commit mà nó được lấy ra (`v1.7.0-2-gc8436c6`) kèm một cảnh báo, vì không
200
- version phát hành nào mô tả đúng đống byte đó. Bản copy đó không bao giờ tự thay đổi.
201
-
202
- Vì vậy làm mới nó là một hành động chủ ý, không phải hệ quả phụ: chạy lại
203
- `./install.sh --tools`. `colab update` sẽ cho biết khi nào đến lúc. **`behind`
204
- nghĩa là đã có một thay đổi CLI ĐÃ PHÁT HÀNH mà máy này chưa có** — phép so sánh
205
- chạy tới tag gần nhất, nên một bản phát hành không đụng gì tới code CLI sẽ không
206
- càm ràm bạn, mà công việc chưa phát hành trong chính checkout của bạn cũng vậy.
207
- (Vế sau chính là lý do mốc trên là tag chứ không phải `HEAD`: đo tới `HEAD` khiến
208
- mọi máy bị đánh dấu cũ suốt quãng từ lúc commit CLI tới tag kế tiếp, mà cách khắc
209
- phục được quảng cáo lại copy *từ* chính cây làm việc đó — nên trên máy đang phát
210
- triển handbook, nó khuyên các service nạp code chưa phát hành.) Nó không bao giờ
211
- ghi đè bản copy, kể cả với `--apply`: đó là bộ công cụ mà các service đang chạy
212
- của bạn đang thực thi. `colab --version` cho biết bạn đang nói chuyện với bản nào (hoặc `npm package` khi
213
- cài qua `npx`/`npm i`), kèm phiên bản của chính bản đó.
214
-
215
- **3. Kiểm lại, rồi chỉ cho audit biết phải soi repo nào.**
277
+ | `--notify-url <url>` | Ghi `notifyUrl` vào `~/.colab/config.json`, chỉ khi khoá đó chưa có. Xem [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
278
+ | `--release` | Checkout clone này về tag phát hành chính thức mới nhất, rồi cài. Là mặc định cho lần cài đầu từ một bản clone mới. |
279
+ | `--trunk` | Checkout `main` rồi cài, kể cả phần chưa phát hành — `@next` của bản clone. |
280
+ | `--dry` | In ra sẽ làm gì, không thay đổi gì. Ghép được với các flag trên. |
281
+ | `--check` | Báo cáo sức khoẻ **chỉ đọc** cho một lần cài trước đó — xem bên dưới. Không nhận flag nào khác; exit 1 nếu có dòng ✗. |
282
+
283
+ **Service luôn-bật (launch agent, daemon, runner headless) phải gọi
284
+ `~/.colab/bin/colab`, không gọi symlink**, vì symlink chạy theo đúng nhánh mà
285
+ clone này đang checkout. Bản đóng băng không bao giờ tự thay đổi: `colab update`
286
+ báo khi nó tụt sau một thay đổi CLI đã phát hành, và chạy lại `./install.sh
287
+ --tools` để làm mới. Vì sao lại làm vậy:
288
+ [`tools/README.md`](tools/README.md#install).
289
+
290
+ **Chỉ cần CLI, không cần skill** thì có trên npm: **`@futurelastic/colab-handbook`**.
291
+ Chưa có bản phát hành chính thức nào lên npm, nên tag mặc định `latest` chỉ là
292
+ bản giữ chỗ; hãy cài từ **`@next`**, các bản ứng viên: `npx
293
+ @futurelastic/colab-handbook@next <lệnh>`, hoặc `npm i -g
294
+ @futurelastic/colab-handbook@next`. Lệnh gõ vẫn là `colab`. Skill không nằm trong package; chúng cài từ một bản clone, vì phải
295
+ symlink vào `~/.claude/skills/`.
296
+
297
+ ### Kiểm tra bản cài
216
298
 
217
299
  ```sh
218
- colab --help # không thấy lệnh? sửa PATH — bước 2 in sẵn dòng cần thêm
219
- colab --version # colab nào đây — working tree, bản đóng băng hay npm package — và phiên bản của nó
220
- $EDITOR ~/.colab/repos.txt # thay các dòng ví dụ bằng repo của bạn
221
- node audit/audit.mjs # báo cáo conformance cho toàn bộ fleet
222
- colab update # các bản copy có đóng dấu đã tụt lại — kể cả CLI đóng băng
300
+ colab --version # colab nào đang trả lời — working tree, bản đóng băng hay npm package — và phiên bản của nó
301
+ ./install.sh --check # chỉ đọc; exit 1 nếu có dòng ✗
302
+ node audit/audit.mjs # báo cáo conformance cho mọi repo đã đăng ký
303
+ colab update # các bản copy có đóng dấu đã tụt lại, kể cả CLI đóng băng
223
304
  ```
224
305
 
225
- Xong thì đọc [`CONVENTIONS.md`](CONVENTIONS.md): mất ~15 phút, và là file chuẩn
226
- tắc duy nhất ở đây.
227
-
228
- ## Adopt vào một repo
229
-
230
- Bản rút gọn — checklist đầy đủ ở
231
- [`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this):
232
-
233
- 1. Trả lời câu 1 một cách trung thực (có production **hôm nay** không, chứ
234
- không phải "sắp có").
235
- 2. Thêm `.github/project.yml`. `colab adopt` hỏi năm câu rồi ghi file giùm bạn —
236
- nó dừng ở phần descriptor và in ra phần còn lại của danh sách này, vì mấy
237
- bước sau không phải việc của nó.
238
- 3. `colab labels --ensure` — các label quy ước không có sẵn, và không phải chỉ
239
- một cái. Một check mà label của nó chưa từng được tạo thì không bao giờ chạy
240
- được.
241
- 4. Dán [`templates/repo-CLAUDE-block.md`](templates/repo-CLAUDE-block.md) vào
242
- `CLAUDE.md` của repo — đây là cách duy nhất để agent phát hiện ra bộ quy ước
243
- này.
244
- 5. Đảm bảo CI đạt hai kết quả bắt buộc: quét secret và build, với phiên bản
245
- toolchain **resolve từ manifest của chính repo** — không bao giờ hardcode.
246
- Copy template nếu thấy tiện.
247
-
248
- Nhánh có sẵn từ trước được **giữ nguyên** (grandfathered). Đừng đổi tên gì cả.
249
-
250
- **Làm việc trong repo không phải của mình?** Nếu không thể commit các file này vào đó,
251
- `colab adopt --local` giữ mọi thứ trong bản clone local của bạn, không có gì lọt vào lịch sử
252
- của chủ repo — xem
253
- [*Working in a repo you don't own*](CONVENTIONS.md#working-in-a-repo-you-dont-own).
306
+ `--check` báo bản đóng băng có tụt sau bản phát hành mới nhất không và lệnh nào
307
+ nó không chạy được, file state có tồn tại không, đã đăng ký repo nào chưa, cả
308
+ hai hooklet pre-commit có chạy được không, và `notifyUrl` có đang trống trong
309
+ khi một observer trên máy đã khai endpoint không. ✗ nghĩa là thứ đã cài đang cũ
310
+ hoặc không dùng được; ⚠ nghĩa là có thứ chưa từng được cài, có thể là cố ý hoặc
311
+ chỉ là chưa làm tới — nên một bản cài mới đúng, chưa đăng ký repo nào và chưa có
312
+ danh sách từ khoá danh tính, sẽ ra các dòng ⚠ và exit 0. Nó không bao giờ tự làm
313
+ mới gì cả. `--check` không có trong v1.11.0 trở về trước; ở những bản đó, hãy theo
314
+ `main` để có nó.
254
315
 
255
316
  ## Vì sao ép buộc ít vậy
256
317
 
257
- Các repo private của chúng ta nằm trên gói GitHub không có branch protection —
258
- không thể cấm push vào `main`. Nên handbook này không giả vờ ép buộc; nó làm
259
- cho việc **tuân thủ rẻ và việc kiểm tra rẻ**. Audit tool báo drift; quy ước
260
- giải thích *vì sao* từng luật tồn tại để bạn tự phán đoán khi nào đáng phá luật.
261
- Khi phá, hãy sửa tài liệu trong cùng PR — một tài liệu mô tả một repo không tồn
262
- tại là thứ tệ nhất trong nghề này.
263
-
264
- **Có hai thứ thì chặn thật, và ranh giới đó là cố ý.** Git hook thì từ chối:
265
- một bản quét secret, và một bản quét danh tính chặn không cho tên máy, đường dẫn
266
- home hay tên khách hàng lọt vào một repo public. Chúng canh phần **phát hành ra
267
- ngoài** — sai lầm duy nhất không thể sửa được, vì history không thu hồi lại được
268
- một khi đã có người clone. Mọi thứ thuộc về *conformance* vẫn chỉ là cảnh báo:
269
- sai một quy ước thì tốn một cuộc trao đổi, còn sai chuyện phát hành thì tốn vĩnh
270
- viễn.
318
+ Không phải gói GitHub nào, owner nào trong một fleet cũng có branch protection,
319
+ nên handbook này không dựa vào nó. Thay vào đó nó làm cho việc **tuân thủ rẻ và
320
+ việc kiểm tra rẻ**: audit báo drift, còn quy ước giải thích *vì sao* từng luật
321
+ tồn tại để bạn tự phán đoán khi nào đáng phá luật. Khi phá, hãy sửa tài liệu
322
+ trong cùng thay đổi đó — một tài liệu mô tả một repo không tồn tại là thứ tệ
323
+ nhất trong nghề này.
324
+
325
+ **Một danh sách ngắn thì chặn thật, và là cố ý:**
326
+
327
+ - **Phát hành ra ngoài.** Git hook từ chối secret, và bản quét danh tính chặn
328
+ tên máy, đường dẫn home hay tên khách hàng lọt vào một repo public. History
329
+ không thu hồi lại được một khi đã có người clone.
330
+ - **Các cổng quanh cú merge**, do `colab` canh: người phải đồng ý trước khi
331
+ merge (trừ khi repo đã cấp `auto-trunk` hoặc thay đổi chỉ là docs), phải có
332
+ quyền cấp trước khi một migration được ship, và release không bao giờ đi kèm
333
+ cú merge.
334
+
335
+ Mọi thứ khác là mặc định — một cách làm tốt — vì sai một quy ước thì chỉ tốn
336
+ một cuộc trao đổi.
271
337
 
272
338
  ## Giấy phép
273
339