@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.11

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 (95) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +312 -3
  3. package/README.vi.md +281 -0
  4. package/audit/audit.mjs +3035 -0
  5. package/package.json +26 -5
  6. package/templates/README.md +257 -0
  7. package/templates/adr-README.md +57 -0
  8. package/templates/branch-name.yml +51 -0
  9. package/templates/ci-laravel.yml +540 -0
  10. package/templates/ci-node.yml +291 -0
  11. package/templates/ci-python.yml +281 -0
  12. package/templates/deploy-xserver.yml +531 -0
  13. package/templates/dist-refs.yml +177 -0
  14. package/templates/docs-lint.mjs +993 -0
  15. package/templates/docs-lint.yml +55 -0
  16. package/templates/gotchas-d-README.md +41 -0
  17. package/templates/identity-vocabulary.example +58 -0
  18. package/templates/npx-launcher.mjs +213 -0
  19. package/templates/pre-commit-dispatch +88 -0
  20. package/templates/pre-commit-identity +267 -0
  21. package/templates/pre-push-guard +137 -0
  22. package/templates/release-auto.yml +475 -0
  23. package/templates/release-tag.yml +245 -0
  24. package/templates/repo-CLAUDE-block.md +21 -0
  25. package/tools/colab +13806 -0
  26. package/tools/lib/adopt.js +882 -0
  27. package/tools/lib/axis-authority.js +96 -0
  28. package/tools/lib/base-ci-verdict.js +93 -0
  29. package/tools/lib/blocked-by.js +262 -0
  30. package/tools/lib/branch-name.js +137 -0
  31. package/tools/lib/checklist.js +143 -0
  32. package/tools/lib/ci-cure.js +512 -0
  33. package/tools/lib/ci-grant.js +307 -0
  34. package/tools/lib/ci-verdict.js +113 -0
  35. package/tools/lib/claim-comments.js +212 -0
  36. package/tools/lib/claim-identity.js +195 -0
  37. package/tools/lib/codeowners.js +208 -0
  38. package/tools/lib/consumer-evidence.js +74 -0
  39. package/tools/lib/container-close.js +141 -0
  40. package/tools/lib/cure-diff.js +267 -0
  41. package/tools/lib/decision-record.js +335 -0
  42. package/tools/lib/dirty-owner.js +150 -0
  43. package/tools/lib/disposition.js +378 -0
  44. package/tools/lib/docs-only.js +156 -0
  45. package/tools/lib/exposure-shape.js +207 -0
  46. package/tools/lib/gate.js +80 -0
  47. package/tools/lib/git.js +1059 -0
  48. package/tools/lib/group-labels.js +120 -0
  49. package/tools/lib/hermetic.js +193 -0
  50. package/tools/lib/identity.js +187 -0
  51. package/tools/lib/install-check.js +278 -0
  52. package/tools/lib/instruction-file.js +302 -0
  53. package/tools/lib/journal.js +430 -0
  54. package/tools/lib/labels.js +653 -0
  55. package/tools/lib/landed.js +230 -0
  56. package/tools/lib/local-adopt.js +133 -0
  57. package/tools/lib/lockfile-drift.js +119 -0
  58. package/tools/lib/machine-trailer.js +83 -0
  59. package/tools/lib/machine.js +238 -0
  60. package/tools/lib/migration-grant.js +641 -0
  61. package/tools/lib/migration-paths.js +135 -0
  62. package/tools/lib/notify-endpoint.js +170 -0
  63. package/tools/lib/notify.js +188 -0
  64. package/tools/lib/npm-publish-guard.js +242 -0
  65. package/tools/lib/orphan-worktree.js +127 -0
  66. package/tools/lib/owner-branch.js +182 -0
  67. package/tools/lib/place.js +782 -0
  68. package/tools/lib/ports.js +167 -0
  69. package/tools/lib/procs.js +185 -0
  70. package/tools/lib/readiness.js +240 -0
  71. package/tools/lib/records.js +185 -0
  72. package/tools/lib/refs-brake.js +95 -0
  73. package/tools/lib/release-channel.js +99 -0
  74. package/tools/lib/release-cut.js +822 -0
  75. package/tools/lib/release-finalize.js +521 -0
  76. package/tools/lib/release-policy.js +358 -0
  77. package/tools/lib/release-tag.js +225 -0
  78. package/tools/lib/ship-batch.js +277 -0
  79. package/tools/lib/ship-roles.js +71 -0
  80. package/tools/lib/ship-target-sync.js +181 -0
  81. package/tools/lib/shipguard.js +317 -0
  82. package/tools/lib/shipped-branch.js +56 -0
  83. package/tools/lib/solo.js +213 -0
  84. package/tools/lib/squash.js +515 -0
  85. package/tools/lib/stale-base.js +70 -0
  86. package/tools/lib/stamp.js +740 -0
  87. package/tools/lib/state.js +262 -0
  88. package/tools/lib/teardown.js +83 -0
  89. package/tools/lib/trust-humans.js +104 -0
  90. package/tools/lib/util.js +98 -0
  91. package/tools/lib/wake.js +188 -0
  92. package/tools/lib/workflow-triggers.js +273 -0
  93. package/tools/lib/writes-authority.js +237 -0
  94. package/tools/lib/yaml.js +101 -0
  95. package/bin/cli.js +0 -3
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 godx-jp
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,4 +1,313 @@
1
- # @futurelastic/colab-handbook
1
+ ***English*** · [Tiếng Việt](README.vi.md)
2
2
 
3
- Placeholder that reserves the name. Install a real release from the `next` or `latest` tag once one is published:
4
- https://github.com/futurelastic/colab-handbook
3
+ # colab-handbook
4
+
5
+ A small set of conventions and tools for running many repos — many coding
6
+ sessions in parallel, humans and AI agents alike — without stepping on each
7
+ other.
8
+
9
+ **If you are an AI agent, stop here and read [`CLAUDE.md`](CLAUDE.md).**
10
+ This file is for humans.
11
+
12
+ *(The normative document — [`CONVENTIONS.md`](CONVENTIONS.md) — is written in
13
+ English so agents and tooling can read it. This is the English front door; the
14
+ Vietnamese one is [`README.vi.md`](README.vi.md). Both are only gateways, not
15
+ normative — when the two disagree, **both are wrong** until they agree with
16
+ `CONVENTIONS.md` again.)*
17
+
18
+ ## What this is
19
+
20
+ A **handbook, not a framework**. It decides **outcomes** — where code merges,
21
+ what a release is, how you announce "I am working on this" — and deliberately
22
+ leaves the **implementation** (your Node version, your test runner, your CI
23
+ file) to each repo.
24
+
25
+ Everything here was distilled from running ~25 real repos, several of them
26
+ production apps maintained almost entirely by AI agents working in parallel
27
+ across many worktrees. The anti-pattern list is not theory: every entry is
28
+ something that actually happened, with the scar to prove it.
29
+
30
+ ### The problem it solves
31
+
32
+ One person on one repo needs none of this. The conventions live in their head,
33
+ and their head is the only place they need to be.
34
+
35
+ That stops working somewhere around the third repo, and it collapses entirely
36
+ once sessions run **in parallel** — several at a time, on different machines,
37
+ some of them agents that will not think to ask. Then every unwritten assumption
38
+ becomes a way to lose work:
39
+
40
+ - two sessions claim the same issue, because neither could see the other had
41
+ started;
42
+ - a feature branch is left checked out on the working tree a dev server reads
43
+ from, and the live app quietly serves unmerged code;
44
+ - code merges and the issue stays open, so the next person re-does it;
45
+ - a repo's documentation describes a repo that no longer exists — which is worse
46
+ than no documentation, because someone will act on it.
47
+
48
+ None of those is a hard problem. They are all the *same* problem: **facts about
49
+ a repo that live in someone's memory instead of in the repo.**
50
+
51
+ ### What it actually does
52
+
53
+ It makes each repo answer a handful of questions about itself, **once**, in a
54
+ file every session reads before touching anything — is there production today,
55
+ who else works here, what breaks if a merge is wrong, how many units of work run
56
+ at a time, how a commit reaches the thing that runs it.
57
+
58
+ Everything else follows from those answers: which branch to merge into, what a
59
+ release even means here, whether a branch is required at all, how much a session
60
+ must write down before it stops. A session never guesses, and two repos never
61
+ disagree about what a word means.
62
+
63
+ The rest of the repo exists to serve that: a CLI that performs the mechanical
64
+ parts, an audit that reports where reality has drifted from what a repo claims,
65
+ and portable session flows so a coding session opens and closes the same way
66
+ everywhere.
67
+
68
+ ### What it is not
69
+
70
+ - **Not a service.** Nothing here is a dependency and nothing phones home. You
71
+ copy what is useful and own the copy — fork it, edit it, delete half of it.
72
+ That is what the licence is for.
73
+ - **Not a CI system, and not an opinion about your stack.** Bring your own
74
+ language, test runner and pipeline. The handbook only asks that the pipeline
75
+ produce two outcomes, and never says how.
76
+ - **Not an enforcement layer**, with one deliberate exception. Conformance is
77
+ advisory, because being wrong about a convention costs a conversation.
78
+ Publication blocks, because history cannot be recalled once anything is
79
+ cloned.
80
+ - **Not a maturity model.** No answer here ranks a repo above another. A repo
81
+ with no production is not a worse repo; it is a repo with fewer gates.
82
+
83
+ If you run one repo alone, read the anti-patterns and take what is useful. If
84
+ you run many — or you work alongside agents that never met the person who set
85
+ the rules — the whole thing is likely to pay for itself faster than it takes to
86
+ read.
87
+
88
+ ## The questions
89
+
90
+ Adopting this means answering five questions about your repo, once, into
91
+ `.github/project.yml` — so no session has to guess, and no two repos disagree
92
+ on what a word means:
93
+
94
+ 1. **Does a deploy target exist today** — and how is it reached: a tag gates
95
+ production, the promotion itself deploys, a human runs a runbook, or
96
+ nothing is live yet?
97
+ 2. **Who else works here** — one person, a team, or the public?
98
+ 3. **What would break if you merged something wrong here** — nothing, only
99
+ the people already in the room, users via the next promotion, or users and
100
+ adopters via a released artifact?
101
+ 4. **One unit of work in flight at a time, or several at once?**
102
+ 5. **By what path does a commit reach the thing that runs it** — a CI
103
+ workflow, a git hook, a documented procedure, a live checkout, a published
104
+ artifact, another system's data, or none of those yet?
105
+
106
+ The answers decide everything that follows: which branch a session merges
107
+ into, what a release is, how much an Issue narrates, what must exist before a
108
+ merge can be undone, whether a branch is even required. Nothing here is asked
109
+ twice, and nothing is asked that the repo already states for itself — its
110
+ default branch, its toolchain, its ports.
111
+
112
+ Issues are **claimed** with an assignee plus the `in-progress` label before
113
+ work starts, so parallel sessions never collide on the same task.
114
+
115
+ The full rules — what each answer resolves to, and why:
116
+ [`CONVENTIONS.md`](CONVENTIONS.md). ~15 minutes to read, and the **single
117
+ normative file** — everything else in the repo serves it.
118
+
119
+ ## Repo layout
120
+
121
+ | Path | What it is |
122
+ |---|---|
123
+ | [`CONVENTIONS.md`](CONVENTIONS.md) | The rules. Normative, the single source of truth (EN). |
124
+ | [`CLAUDE.md`](CLAUDE.md) | The entry point for AI agents — the operational distillation (EN). |
125
+ | [`project.schema.md`](project.schema.md) | Field reference for `.github/project.yml`. |
126
+ | [`templates/`](templates/) | **Copy-and-own** starting points: CI, release, git hooks (a secret scan and an identity scan), and the `CLAUDE.md` block for adopting repos. **Nothing is called remotely** — copy it, edit it, own it. Templates, not scaffolding, because scaffolding only reaches repos created after it shipped. |
127
+ | [`tools/`](tools/) | `colab` — a small CLI (optional): adopt a repo, claim issues, allocate ports, manage worktrees, and merge a finished branch to trunk when the repo grants it. JSON state, zero dependencies. Full command reference: [`tools/README.md`](tools/README.md). |
128
+ | [`audit/`](audit/) | An external conformance checker. Reads all your repos — every owner, including local-only ones — and reports drift in a single run. Advisory only, never blocking. `--identity` additionally scans public repository descriptions and topics, which no git hook can see. What each check means: [`audit/README.md`](audit/README.md). |
129
+ | [`skills/`](skills/) | Portable session flow: `code-triage` (pick the next task, flagging hard ones for a plan) → `code-start` (open a session; runs `code-plan` when flagged) → `code-wrap` (distill + gate + hand off) → `code-ship` (grade + merge, human-authorized), plus `code-sweep` (clear out everything ALREADY DONE in one repo — or just a named set of issues or one session — running `code-wrap`+`code-ship` on each) `handbook-sync` (bring ONE repo up to the latest handbook, run from inside it), and `release-rung` (the manual fallback and explainer for the release workflow, which is the driver: walk one repo's release rung from a coordinator session — candidate, test period, `release-hold` veto, final — through `colab release cut`/`finalize`, never by hand), and `migration-review` (for whoever a repo binds to the migration-reviewer role: review a branch's migrations against the deploy engine and end in one verdict — GRANT with a review record, REWORK with a brief, or ESCALATE to a human — with a blind test set to run before binding a new reviewer). Installed as Claude Code skills by [`install.sh`](install.sh) — see *Setting up a machine* below. |
130
+ | [`install.sh`](install.sh) | Sets up **your machine**: skills, the `colab` CLI, the pre-commit hook, the fleet list. Idempotent, and `--dry` shows you everything first. |
131
+
132
+ ## Install the CLI from npm
133
+
134
+ The `colab` CLI is also published as a public npm package, **`@futurelastic/colab-handbook`**. The command you type stays `colab`.
135
+
136
+ ```sh
137
+ npx @futurelastic/colab-handbook <command> # one-off, nothing installed, no npm account needed
138
+ npm i -g @futurelastic/colab-handbook # then: colab <command>
139
+ npm i -g @futurelastic/colab-handbook@next # release candidates (vX.Y.Z-rc.N) instead of finals
140
+ ```
141
+
142
+ The package carries what `colab` reads at runtime — the CLI, its `lib/`, `templates/` and `audit/audit.mjs` — and nothing else; `colab template` and `colab adopt` work from the registry copy and stamp the package's own version. The skills are **not** in it: they install with `./install.sh` from a clone (below), because they must symlink into `~/.claude/skills/`. Every tarball is checked file by file against an allowlist in CI (`scripts/check-pack-allowlist.mjs`).
143
+
144
+ ## Setting up a machine
145
+
146
+ Once per machine, before you adopt anything into a repo.
147
+
148
+ **You need:** `git`; `node` ≥ 18 (`.nvmrc` pins 22, which is what CI here runs);
149
+ `gh` **logged in** (`gh auth login`) — claims, the skills and the audit's remote
150
+ targets are all useless without it, and the failure surfaces much later as
151
+ something confusing; and `gitleaks` only if you want the pre-commit hook.
152
+ `install.sh` checks every one of these and reports what is missing before it
153
+ changes anything.
154
+
155
+ **1. Clone it somewhere permanent** — with the rest of your code, not in a
156
+ scratch directory.
157
+
158
+ ```sh
159
+ git clone https://github.com/futurelastic/colab-handbook.git ~/code/colab-handbook
160
+ cd ~/code/colab-handbook
161
+ ```
162
+
163
+ **This clone is infrastructure, not a download.** The skills install as symlinks
164
+ *into this working tree*: delete the clone and every session on the machine
165
+ loses them, and whichever branch it has checked out is the version of the skills
166
+ every session gets. So keep it on `main` unless you are actively working on the
167
+ handbook itself. `install.sh` warns if it finds itself under `/tmp`,
168
+ `~/Downloads` or `~/Desktop`.
169
+
170
+ **2. Install.**
171
+
172
+ ```sh
173
+ ./install.sh --all --dry # see exactly what would happen; changes nothing
174
+ ./install.sh --all # skills + colab CLI + pre-commit hook + fleet list
175
+ ```
176
+
177
+ `--all` is the recommended first run. Everything it does is a symlink or a copy,
178
+ it is idempotent, and it never overwrites anything it did not create — your own
179
+ skill, or an existing `~/.colab/repos.txt`, is left alone with a warning. Bare
180
+ `./install.sh` installs the skills and nothing else, if that is genuinely all
181
+ you want.
182
+
183
+ | Flag | What it does |
184
+ |---|---|
185
+ | *(none)* | Symlink `skills/` into `~/.claude/skills/`, so they are available in every repo you open. |
186
+ | `--tools` | Two installs of one CLI: a **symlink** at `~/.local/bin/colab` for your sessions (checking that directory is really on your `PATH`, and printing the exact line to add if not), plus a stamped **frozen copy** at `~/.colab/bin/colab` for always-on services — see below. |
187
+ | `--hooks` | Point this clone's git at `.githooks/`, whose `pre-commit` runs every check in `pre-commit.d/` — a gitleaks secret scan, and an identity scan that needs a vocabulary you supply by path and keep outside every repo (see [`templates/README.md`](templates/README.md)). `core.hooksPath` lives in `.git/config`, so it is per-clone, per-machine, and never travels with the repo. |
188
+ | `--fleet` | Seed `~/.colab/repos.txt` from `audit/repos.txt`, only if it is absent. The seed is format notes and commented placeholders — it registers **nothing**; `colab register <path>` (step 3) is what fills it. That list stays machine-local on purpose: it names your private repos, and this repo is public. |
189
+ | `--all` | `--tools --hooks --fleet`. |
190
+ | `--notify-url <url>` | Seed `notifyUrl` in `~/.colab/config.json` with a local observer's events URL, only when the key is absent — an existing value is never overwritten. Without the flag, `--tools` seeds it from `~/.colab/notify-endpoint` when a local observer declared its URL there, and otherwise prints that `notifyUrl` is unset and which events that drops. See [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
191
+ | `--dry` | Print what would happen, change nothing. Combines with all of the above. |
192
+ | `--check` | **Read-only** health report on what an earlier install left behind — see *Checking an install* below. Takes no other flag; exit 1 on any ✗ row. |
193
+
194
+ `--tools` also creates an **empty** `~/.colab/state.json` when there is none (it never
195
+ touches an existing one). Without that, the file appeared only on the first
196
+ state-changing `colab` command, and anything reading it on a fresh machine got an
197
+ error where it should have seen an empty fleet.
198
+
199
+ **Always-on services must call `~/.colab/bin/colab`.** The symlinked CLI follows
200
+ whatever branch this clone has checked out — deliberate for a human session, and
201
+ wrong for anything that outlives one. A daemon, a launch agent or a headless
202
+ runner started months ago would silently change behaviour because somebody
203
+ checked out an unrelated branch, and nothing would report it: the process keeps
204
+ working, differently. So `--tools` also writes a **copy** to `~/.colab/bin/`
205
+ (honouring `COLAB_HOME`), stamped with the handbook version it was taken from —
206
+ or, when that tree sits ahead of the last tag, with the commit it was taken from
207
+ (`v1.7.0-2-gc8436c6`) and a warning, because no released version describes those
208
+ bytes. That copy never moves on its own.
209
+
210
+ Refreshing it is therefore an act, never a side effect: re-run `./install.sh
211
+ --tools`. `colab update` tells you when it is due. **`behind` means a released
212
+ CLI change exists that this machine lacks** — the comparison runs to the latest
213
+ tag, so a release that changed no CLI code does not nag you, and unreleased work
214
+ in your own checkout does not either. (That last part is why the bound is the tag
215
+ rather than `HEAD`: measuring to `HEAD` marked every machine stale for the whole
216
+ window between a CLI commit and the next tag, and the advertised remedy copies
217
+ *from* that same working tree — so on a machine developing the handbook it
218
+ advised services to adopt untagged code.) It never rewrites the copy, not even
219
+ with `--apply`: that is the toolchain your running services are executing.
220
+ `colab --version` says which of the two you are talking to (or `npm package` for an
221
+ `npx`/`npm i` install), and prints that install's version. The frozen copy carries
222
+ `tools/` only, so `colab template` refuses there — run it from the working tree.
223
+
224
+ **3. Verify, and register your repos.**
225
+
226
+ ```sh
227
+ colab --help # not found? fix your PATH — step 2 prints the exact line
228
+ colab --version # which colab is this — working tree, frozen copy, or npm package — and its version
229
+ colab register /path/to/repo # once per repo — writes repos.txt AND config.json, so they agree
230
+ node audit/audit.mjs # a conformance report across the whole fleet
231
+ colab update # stamped copies that fell behind — the frozen CLI included
232
+ ```
233
+
234
+ `colab register` is the way in; hand-editing `~/.colab/repos.txt` still works for
235
+ the audit, but leaves `config.json` — where the CLI reserves each repo's ports —
236
+ unaware of the repo. A remote-only audit target (`owner/name`, nothing cloned) is
237
+ the one entry you add to `repos.txt` by hand. A repo not yet adopted then needs
238
+ `colab adopt` and `colab labels --ensure` — see *Adopting it into a repo* below.
239
+
240
+ ### Checking an install
241
+
242
+ ```sh
243
+ ./install.sh --check # read-only; exit 1 on any ✗ row
244
+ ```
245
+
246
+ A frozen copy never breaks — it gets **old**, and an old complete copy answers
247
+ normally for every command it knows until something asks for one added after it
248
+ was frozen. `--check` is the report nothing else gives: whether the frozen copy is
249
+ behind the latest release, **which commands it does not dispatch**, whether the
250
+ state file exists, whether anything is registered, whether both pre-commit
251
+ hooklets can actually run (gitleaks, and the identity vocabulary), and whether
252
+ `notifyUrl` is unset while a local observer declared an endpoint. ✗ means
253
+ something installed here is stale or unusable; ⚠ means something was never set
254
+ up, which may be deliberate. It never refreshes anything — re-freezing stays your
255
+ call: `./install.sh --tools`.
256
+
257
+ Then read [`CONVENTIONS.md`](CONVENTIONS.md): ~15 minutes, and the only
258
+ normative file here.
259
+
260
+ ## Adopting it into a repo
261
+
262
+ The short version — the full checklist is
263
+ [`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this):
264
+
265
+ 1. Answer question 1 honestly (is there production **today**, not "soon").
266
+ 2. Add `.github/project.yml`. `colab adopt` asks the five questions and writes
267
+ the file for you — it stops at the descriptor and prints the rest of this
268
+ list, because the remaining steps are not its to take.
269
+ 3. `colab labels --ensure` — the convention labels do not exist by default, and
270
+ there are more than one. A check whose label was never created can never
271
+ fire.
272
+ 4. Paste [`templates/repo-CLAUDE-block.md`](templates/repo-CLAUDE-block.md)
273
+ into the repo's `CLAUDE.md` — this is the only way agents discover these
274
+ conventions.
275
+ 5. Make sure CI produces the two required outcomes: a secret scan and a build,
276
+ with toolchain versions **resolved from the repo's own manifest** — never
277
+ hardcoded. Copy a template if it helps.
278
+
279
+ Pre-existing branches are **grandfathered**. Do not rename anything.
280
+
281
+ **Working in a repo you don't own?** If committing these files there is not an option,
282
+ `colab adopt --local` keeps everything in your local clone instead, and nothing lands in
283
+ the owner's history — see
284
+ [*Working in a repo you don't own*](CONVENTIONS.md#working-in-a-repo-you-dont-own).
285
+
286
+ ## Why so little enforcement
287
+
288
+ Our private repos sit on a GitHub plan without branch protection — pushes to
289
+ `main` cannot be forbidden. So this handbook does not pretend to enforce; it
290
+ makes **compliance cheap and checking cheap**. The audit tool reports drift; the
291
+ conventions explain *why* each rule exists, so you can judge for yourself when
292
+ breaking one is worth it. When you do break one, fix the documentation in the
293
+ same PR — a document describing a repo that does not exist is the worst thing in
294
+ this business.
295
+
296
+ **Two things do block, and the line between them is deliberate.** The git hooks
297
+ refuse: a secret scan, and an identity scan that stops a hostname, a home path
298
+ or a customer's name reaching a public repo. Those guard **publication**, which
299
+ is the one mistake that cannot be undone — history cannot be recalled once
300
+ anything is cloned. Everything about *conformance* stays advisory, because being
301
+ wrong about a convention costs a conversation, and being wrong about publication
302
+ costs forever.
303
+
304
+ ## License
305
+
306
+ [MIT License](LICENSE). Copy what is useful — that is what this repo is
307
+ for. The licence is the legal half of "copy-and-own": you may use, modify and
308
+ redistribute anything here, including in closed-source work, provided you keep
309
+ the notice. It also carries an express patent grant, and reserves the project's
310
+ trademarks.
311
+
312
+ Adopting a convention costs you nothing and grants us nothing. Nothing here
313
+ phones home, and there is no obligation to contribute anything back.
package/README.vi.md ADDED
@@ -0,0 +1,281 @@
1
+ [English](README.md) · ***Tiếng Việt***
2
+
3
+ # colab-handbook
4
+
5
+ Bộ quy ước và công cụ nhỏ để vận hành nhiều repo — nhiều phiên code song song,
6
+ người thật lẫn AI agent — mà không giẫm chân nhau.
7
+
8
+ **Nếu bạn là AI agent, dừng ở đây và đọc [`CLAUDE.md`](CLAUDE.md).**
9
+ File này dành cho con người.
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`.)*
16
+
17
+ ## Đây là cái gì
18
+
19
+ Một cuốn **handbook, không phải framework**. Nó quyết định **kết quả** — code
20
+ merge vào đâu, release là gì, báo "tôi đang làm việc này" bằng cách nào — và cố
21
+ tình để **cách hiện thực** (phiên bản Node, test runner, file CI của bạn) cho
22
+ từng repo tự quyết.
23
+
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.
28
+
29
+ ### Nó giải quyết vấn đề gì
30
+
31
+ Một người, một repo thì chẳng cần gì trong đây cả. Quy ước nằm trong đầu người
32
+ đó, và trong đầu là chỗ duy nhất nó cần nằm.
33
+
34
+ Cách đó hết hiệu lực đâu đó quanh cái repo thứ ba, và sụp hẳn khi các phiên bắt
35
+ đầu chạy **song song** — vài phiên một lúc, trên nhiều máy khác nhau, có những
36
+ phiên là agent và chúng sẽ không nghĩ ra chuyện phải hỏi. Lúc đó mọi giả định
37
+ không viết ra đều thành một cách để mất việc:
38
+
39
+ - hai phiên cùng claim một issue, vì chẳng bên nào thấy được bên kia đã bắt đầu;
40
+ - một nhánh feature bị bỏ quên trên chính working tree mà dev server đang đọc,
41
+ thế là app đang chạy lặng lẽ phục vụ code chưa merge;
42
+ - code đã merge mà issue vẫn mở, nên người sau làm lại từ đầu;
43
+ - tài liệu của một repo mô tả một repo không còn tồn tại — thứ này tệ hơn là
44
+ không có tài liệu, vì kiểu gì cũng có người tin theo mà làm.
45
+
46
+ Không cái nào trong đó là vấn đề khó. Chúng đều là **cùng một** vấn đề: **những
47
+ sự thật về một repo lại nằm trong trí nhớ của ai đó thay vì nằm trong repo.**
48
+
49
+ ### Thực chất nó làm gì
50
+
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ừ.
60
+
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.
64
+
65
+ ### Nó không phải cái gì
66
+
67
+ - **Không phải một service.** Không có gì ở đây là dependency và không có gì gửi
68
+ dữ liệu về. Bạn copy cái nào thấy dùng được rồi sở hữu bản copy đó — fork,
69
+ sửa, xoá bớt nửa cũng được. Giấy phép sinh ra để làm việc đó.
70
+ - **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
+ ngữ, test runner, pipeline — của bạn cả. Handbook chỉ yêu cầu pipeline cho ra
72
+ 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.
76
+ - **Không phải thang đo độ trưởng thành.** Không câu trả lời nào ở đây xếp repo
77
+ này trên repo kia. Một repo chưa có production không phải repo tệ hơn; nó là
78
+ repo có ít cổng hơn.
79
+
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.
84
+
85
+ ## Năm câu hỏi
86
+
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ó.
116
+
117
+ ## Cấu trúc repo
118
+
119
+ | Đường dẫn | Là gì |
120
+ |---|---|
121
+ | [`CONVENTIONS.md`](CONVENTIONS.md) | Luật. Chuẩn tắc, nguồn sự thật duy nhất (EN). |
122
+ | [`CLAUDE.md`](CLAUDE.md) | Cửa vào cho AI agent — bản chưng cất vận hành (EN). |
123
+ | [`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`).
141
+
142
+ ## Cài đặt máy
143
+
144
+ Làm một lần cho mỗi máy, trước khi adopt handbook vào repo nào.
145
+
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ì.
152
+
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.
155
+
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.
180
+
181
+ | Flag | Làm gì |
182
+ |---|---|
183
+ | *(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. |
187
+ | `--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.**
216
+
217
+ ```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
223
+ ```
224
+
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).
254
+
255
+ ## Vì sao ép buộc ít vậy
256
+
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.
271
+
272
+ ## Giấy phép
273
+
274
+ [MIT License](LICENSE). Cứ copy những gì thấy dùng được — repo này sinh
275
+ ra để làm việc đó. Giấy phép là nửa pháp lý của "copy-and-own": bạn được dùng,
276
+ sửa và phát hành lại mọi thứ ở đây, kể cả trong sản phẩm đóng mã nguồn, miễn là
277
+ giữ lại phần ghi chú bản quyền. Nó cũng kèm một điều khoản cấp quyền sáng chế
278
+ rõ ràng, và giữ lại quyền với thương hiệu của dự án.
279
+
280
+ Việc bạn adopt một quy ước không tốn gì của bạn và cũng không cho chúng tôi
281
+ quyền gì. Không có gì ở đây gửi dữ liệu về, và không có nghĩa vụ đóng góp ngược.