@futurelastic/colab-handbook 1.12.0-rc.69 → 1.12.0-rc.71

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.
package/README.md CHANGED
@@ -13,7 +13,7 @@ This file is for humans.
13
13
 
14
14
  ```sh
15
15
  git clone https://github.com/futurelastic/colab-handbook.git ~/code/colab-handbook
16
- cd ~/code/colab-handbook && ./install.sh --all # skills + colab CLI + hooks; --dry shows it first
16
+ cd ~/code/colab-handbook && ./install.sh --all # skills + colab CLI + hooks, from the newest release; --dry shows it first
17
17
  cd /path/to/your-repo
18
18
  colab adopt # asks only what it cannot detect, writes .github/project.yml
19
19
  colab labels --ensure # creates the convention labels
@@ -23,7 +23,8 @@ colab register # adds the repo to this machine's fleet list
23
23
  Then, in an agent session in that repo, run `/code-start <issue-number>`. With an
24
24
  agent at hand, `/handbook-sync` replaces the last three commands and also does
25
25
  the rest of adoption (see [*Adopting it into a repo*](#adopting-it-into-a-repo)).
26
- You need `git`, `node` ≥ 18 and `gh` logged in (`gh auth login`).
26
+ You need `git`, `node` ≥ 18 and `gh` ≥ 2.94 logged in (`gh auth login`); distro
27
+ packages often ship an older `gh`, so install it from [cli.github.com](https://cli.github.com).
27
28
 
28
29
  *([`CONVENTIONS.md`](CONVENTIONS.md) is the normative document, written in
29
30
  English so agents and tooling can read it. This file and the Vietnamese
@@ -133,18 +134,24 @@ it end to end.
133
134
 
134
135
  ## The five questions
135
136
 
136
- Adopting means answering these about your repo, once, into
137
- `.github/project.yml`. `colab adopt` asks them as numbered menus:
137
+ Adopting means answering these about your repo into `.github/project.yml`.
138
+ `colab adopt` asks only the two that change a gate (1 and 3), as numbered menus;
139
+ the other three are optional and can be answered any time later:
138
140
 
139
- | # | Question | Writes |
140
- |---|---|---|
141
- | 1 | Does a deploy target exist **today** (not "soon"), and how is it reached — a tag, the promotion itself, a human running a runbook, or nothing yet? | `production` + `deploy` |
142
- | 2 | Who else works here — just you, a team, or the public? | `room` |
143
- | 3 | What would break if you merged something wrong here — nothing, only people already in the room, users via the next promotion, or users and adopters via a released artifact? | `exposure` |
144
- | 4 | May a human commit straight to trunk alongside worktree sessions — freely, with declared intent, or never? | `writes` |
145
- | 5 | By what path does a commit reach the thing that runs it — a CI workflow, a git hook, a documented procedure, a live checkout, a published artifact, another system's data, or none yet? | `channels` |
146
-
147
- Nothing is asked that the repo already states — its default branch (`trunk`),
141
+ | # | Question | Writes | At adoption |
142
+ |---|---|---|---|
143
+ | 1 | Does a deploy target exist **today** (not "soon"), and how is it reached — a tag, the promotion itself, a human running a runbook, or nothing yet? | `production` + `deploy` | asked |
144
+ | 2 | Who else works here — just you, a team, or the public? | `room` | optional — `colab adopt --axis room` |
145
+ | 3 | What would break if you merged something wrong here — nothing, only people already in the room, users via the next promotion, or users and adopters via a released artifact? | `exposure` | asked — a human's answer |
146
+ | 4 | May a human commit straight to trunk alongside worktree sessions — freely, with declared intent, or never? | `writes` | optional — `colab adopt --axis writes` |
147
+ | 5 | By what path does a commit reach the thing that runs it — a CI workflow, a git hook, a documented procedure, a live checkout, a published artifact, another system's data, or none yet? | `channels` | optional — `colab adopt --axis channels` |
148
+
149
+ **Answering question 3 is a human's act** when the answer is "nothing" or "only
150
+ people already in the room". An agent can drive everything else; when it gets
151
+ there, `colab adopt` prints, as its first line, the one command the human runs.
152
+
153
+ Nothing is asked that the repo already states — its default branch (`trunk`,
154
+ kept as it is: a `master` default is fine, nothing needs renaming),
148
155
  its toolchain, its ports are detected. Gate count, release ritual and whether a
149
156
  branch is mandatory are derived from the answers. What each answer resolves to,
150
157
  and why: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) and
@@ -163,7 +170,7 @@ edits.
163
170
  By hand, the same steps (full checklist:
164
171
  [`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this)):
165
172
 
166
- 1. `colab adopt` — answers the five questions and writes
173
+ 1. `colab adopt` — answers the two gating questions and writes
167
174
  `.github/project.yml`. It stops there and prints the remaining steps.
168
175
  2. `colab labels --ensure` — the convention labels do not exist by default. A
169
176
  check whose label was never created can never fire.
@@ -238,10 +245,23 @@ migration hold with or without it.
238
245
  ## Setting up a machine
239
246
 
240
247
  Once per machine. Clone somewhere permanent — the skills are symlinks *into
241
- this working tree*, so whichever branch it has checked out is the version every
242
- session gets; keep it on `main`. `install.sh` checks its prerequisites before it
243
- changes anything, never overwrites what it did not create, and `--dry` prints
244
- the plan first.
248
+ this working tree*, so whatever it has checked out is the version every session
249
+ gets. `install.sh` checks its prerequisites before it changes anything, never
250
+ overwrites what it did not create, and `--dry` prints the plan first.
251
+
252
+ **Which version you get.** `main` runs ahead of the last final release, so the
253
+ first install from a fresh clone checks out the **newest final release tag**
254
+ (`vX.Y.Z`, never a release candidate) and installs from that — the same
255
+ default npm gives you. To follow `main` instead, unreleased work included, run
256
+ the first install with `--trunk`. Every run prints which one you are on.
257
+ Later moves are explicit:
258
+
259
+ - to a newer release: `./install.sh --release`;
260
+ - from a release back to `main`: `git checkout main && ./install.sh --trunk` (an
261
+ older release's installer does not know `--trunk`, so check out `main` first).
262
+
263
+ A clone with uncommitted changes is never moved, and a re-run without either
264
+ flag keeps whatever is checked out.
245
265
 
246
266
  | Flag | What it does |
247
267
  |---|---|
@@ -251,6 +271,8 @@ the plan first.
251
271
  | `--fleet` | Seed `~/.colab/repos.txt` with format notes only, if absent. It stays machine-local because it names your private repos; `colab register` fills it. |
252
272
  | `--all` | `--tools --hooks --fleet`. |
253
273
  | `--notify-url <url>` | Seed `notifyUrl` in `~/.colab/config.json`, only if the key is absent. See [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
274
+ | `--release` | Check this clone out at the newest final release tag, then install. The default for a first install from a fresh clone. |
275
+ | `--trunk` | Check out `main` and install it, unreleased work included — the clone's `@next`. |
254
276
  | `--dry` | Print what would happen, change nothing. Combines with the flags above. |
255
277
  | `--check` | **Read-only** health report on an earlier install — see below. Takes no other flag; exit 1 on any ✗ row. |
256
278
 
@@ -262,9 +284,11 @@ branch this clone has checked out. The frozen copy never moves on its own:
262
284
  [`tools/README.md`](tools/README.md#install).
263
285
 
264
286
  **The CLI alone, without the skills,** is on npm as
265
- **`@futurelastic/colab-handbook`** — `npx @futurelastic/colab-handbook <command>`,
266
- or `npm i -g @futurelastic/colab-handbook` (`@next` for release candidates). The
267
- command is still `colab`. The skills are not in the package; they install from a
287
+ **`@futurelastic/colab-handbook`**. No final release has been published to npm
288
+ yet, so the default `latest` tag holds only a placeholder; install from
289
+ **`@next`**, the release candidates: `npx @futurelastic/colab-handbook@next
290
+ <command>`, or `npm i -g @futurelastic/colab-handbook@next`. The command is
291
+ still `colab`. The skills are not in the package; they install from a
268
292
  clone, because they must symlink into `~/.claude/skills/`.
269
293
 
270
294
  ### Checking an install
@@ -281,7 +305,10 @@ which commands it does not dispatch, whether the state file exists, whether
281
305
  anything is registered, whether both pre-commit hooklets can run, and whether
282
306
  `notifyUrl` is unset while a local observer declared an endpoint. ✗ means
283
307
  something installed is stale or unusable; ⚠ means something was never set up,
284
- which may be deliberate. It never refreshes anything.
308
+ which may be deliberate or just not done yet — so a correct fresh install, with
309
+ no repo registered and no identity vocabulary, reports ⚠ rows and exits 0. It
310
+ never refreshes anything. `--check` is not in v1.11.0 or earlier; on such a
311
+ release, follow `main` to get it.
285
312
 
286
313
  ## Why so little enforcement
287
314
 
package/README.vi.md CHANGED
@@ -12,7 +12,7 @@ File này dành cho con người.
12
12
 
13
13
  ```sh
14
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; --dry để xem trước
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
16
  cd /duong-dan/toi/repo-cua-ban
17
17
  colab adopt # chỉ hỏi những gì không tự dò ra được, rồi ghi .github/project.yml
18
18
  colab labels --ensure # tạo các label quy ước
@@ -22,7 +22,8 @@ colab register # đưa repo vào danh sách fleet của máy này
22
22
  Sau đó, trong một phiên agent ở repo đó, chạy `/code-start <số-issue>`. Có agent
23
23
  trong tay thì `/handbook-sync` thay được ba lệnh cuối và làm nốt phần adopt còn
24
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` đã đăng nhập (`gh auth login`).
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).
26
27
 
27
28
  *([`CONVENTIONS.md`](CONVENTIONS.md) là tài liệu chuẩn tắc, viết bằng tiếng Anh
28
29
  để agent và tool đọc được. File này và bản tiếng Anh [`README.md`](README.md)
@@ -132,18 +133,24 @@ còn lại của `CONVENTIONS.md` là tài liệu tra cứu — cần gì tra n
132
133
 
133
134
  ## Năm câu hỏi
134
135
 
135
- Adopt nghĩa là trả lời mấy câu này về repo của bạn, một lần, vào
136
- `.github/project.yml`. `colab adopt` hỏi chúng dưới dạng menu đánh số:
136
+ Adopt nghĩa là trả lời mấy câu này về repo của bạn vào `.github/project.yml`.
137
+ `colab adopt` chỉ hỏi hai câu làm thay đổi cổng (1 và 3), dưới dạng menu đánh
138
+ 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:
137
139
 
138
- | # | Câu hỏi | Ghi vào |
139
- |---|---|---|
140
- | 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` |
141
- | 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` |
142
- | 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` |
143
- | 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` |
144
- | 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` |
145
-
146
- Không câu nào hỏi cái repo đã tự nói sẵn — nhánh mặc định (`trunk`), toolchain,
140
+ | # | Câu hỏi | Ghi vào | Lúc adopt |
141
+ |---|---|---|---|
142
+ | 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 |
143
+ | 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` |
144
+ | 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 |
145
+ | 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` |
146
+ | 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` |
147
+
148
+ **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
149
+ "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 đó,
150
+ `colab adopt` in ra, ngay dòng đầu tiên, đúng một lệnh để người thật chạy.
151
+
152
+ 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
153
+ như đang có: nhánh mặc định tên `master` vẫn hợp lệ, không cần đổi tên), toolchain,
147
154
  port đều được tự dò. Số cổng, nghi thức release và việc có bắt buộc phải có
148
155
  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ì
149
156
  sao: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) và
@@ -161,7 +168,7 @@ nhất mà không làm mất phần bạn đã sửa.
161
168
  Làm bằng tay thì cũng đúng các bước đó (checklist đầy đủ:
162
169
  [`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this)):
163
170
 
164
- 1. `colab adopt` — trả lời năm câu hỏi và ghi `.github/project.yml`. Nó dừng ở
171
+ 1. `colab adopt` — trả lời hai câu hỏi về cổng và ghi `.github/project.yml`. Nó dừng ở
165
172
  đó và in ra các bước còn lại.
166
173
  2. `colab labels --ensure` — các label quy ước không có sẵn. Một check mà label
167
174
  của nó chưa từng được tạo thì không bao giờ chạy được.
@@ -236,10 +243,23 @@ quyền cấp trước khi chạy migration vẫn đứng vững dù có nó hay
236
243
  ## Cài đặt máy
237
244
 
238
245
  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ỏ
239
- *thẳng vào working tree này*, nên repo đang checkout nhánh nào thì mọi phiên
240
- dùng đúng bản skill của nhánh đó; hãy để nó ở `main`. `install.sh` kiểm tra đủ
241
- điều kiện trước khi đụng vào gì, không bao giờ ghi đè thứ nó không tạo ra, và
242
- `--dry` in kế hoạch ra trước.
246
+ *thẳng vào working tree này*, nên repo đang checkout cái gì thì mọi phiên dùng
247
+ đúng bản skill đó. `install.sh` kiểm tra đủ điều kiện trước khi đụng vào gì,
248
+ không bao giờ ghi đè thứ nó không tạo ra, và `--dry` in kế hoạch ra trước.
249
+
250
+ **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
251
+ 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
252
+ 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ừ đó —
253
+ 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
254
+ 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ề
255
+ sau đều phải chủ động:
256
+
257
+ - lên bản phát hành mới hơn: `./install.sh --release`;
258
+ - từ một bản phát hành quay về `main`: `git checkout main && ./install.sh --trunk`
259
+ (installer của bản phát hành cũ không biết `--trunk`, nên checkout `main` trước).
260
+
261
+ Clone đang có thay đổi chưa commit thì không bao giờ bị chuyển, và chạy lại
262
+ không kèm flag nào thì giữ nguyên thứ đang checkout.
243
263
 
244
264
  | Flag | Làm gì |
245
265
  |---|---|
@@ -249,6 +269,8 @@ dùng đúng bản skill của nhánh đó; hãy để nó ở `main`. `install.
249
269
  | `--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. |
250
270
  | `--all` | `--tools --hooks --fleet`. |
251
271
  | `--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). |
272
+ | `--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. |
273
+ | `--trunk` | Checkout `main` rồi cài, kể cả phần chưa phát hành — `@next` của bản clone. |
252
274
  | `--dry` | In ra sẽ làm gì, không thay đổi gì. Ghép được với các flag trên. |
253
275
  | `--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 ✗. |
254
276
 
@@ -259,10 +281,11 @@ báo khi nó tụt sau một thay đổi CLI đã phát hành, và chạy lại
259
281
  --tools` để làm mới. Vì sao lại làm vậy:
260
282
  [`tools/README.md`](tools/README.md#install).
261
283
 
262
- **Chỉ cần CLI, không cần skill** thì có trên npm: **`@futurelastic/colab-handbook`**
263
- — `npx @futurelastic/colab-handbook <lệnh>`, hoặc `npm i -g
264
- @futurelastic/colab-handbook` (`@next` cho bản ứng viên). Lệnh gõ vẫn là
265
- `colab`. Skill không nằm trong package; chúng cài từ một bản clone, vì phải
284
+ **Chỉ cần CLI, không cần skill** thì có trên npm: **`@futurelastic/colab-handbook`**.
285
+ 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à
286
+ bản giữ chỗ; hãy cài từ **`@next`**, các bản ứng viên: `npx
287
+ @futurelastic/colab-handbook@next <lệnh>`, hoặc `npm i -g
288
+ @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
266
289
  symlink vào `~/.claude/skills/`.
267
290
 
268
291
  ### Kiểm tra bản cài
@@ -278,8 +301,11 @@ colab update # các bản copy có đóng dấu đã tụt lại, k
278
301
  nó không chạy được, file state có tồn tại không, đã đăng ký repo nào chưa, cả
279
302
  hai hooklet pre-commit có chạy được không, và `notifyUrl` có đang trống trong
280
303
  khi một observer trên máy đã khai endpoint không. ✗ nghĩa là thứ đã cài đang cũ
281
- hoặc không dùng được; ⚠ nghĩa là có thứ chưa từng được cài, có thể là cố ý. Nó
282
- không bao giờ tự làm mới gì cả.
304
+ 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
305
+ 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ó
306
+ 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
307
+ mới gì cả. `--check` không có trong v1.11.0 trở về trước; ở những bản đó, hãy theo
308
+ `main` để có nó.
283
309
 
284
310
  ## Vì sao ép buộc ít vậy
285
311
 
package/audit/audit.mjs CHANGED
@@ -82,7 +82,7 @@ const {
82
82
  // encode the VALIDATOR half (report every violation) separately from `colab adopt`'s CONSTRUCTOR
83
83
  // half (does declaring this exposure value stay possible at all?). Same install.sh-freezes-
84
84
  // tools/lib/ reasoning as the other requires on this page.
85
- const { evaluateExposure } = require("../tools/lib/exposure-shape.js");
85
+ const { evaluateExposure, singleTrunkViolation } = require("../tools/lib/exposure-shape.js");
86
86
  // #208's `writes` split precedence ladder — same shared-module reasoning as axisAuthority
87
87
  // above, reused for a second axis rather than a bespoke second mechanism.
88
88
  const writesAuthority = require("../tools/lib/writes-authority.js");
@@ -1100,6 +1100,10 @@ function renderDuration(age) {
1100
1100
 
1101
1101
  function auditRepo(target, ctx) {
1102
1102
  const src = makeSource(target);
1103
+ // #522: the branch list is read by the single-trunk rule (tier B / exposure none|released) AND the
1104
+ // trunk-exists check below — one read, so a remote target costs one API listing, not three.
1105
+ let branchesMemo;
1106
+ const branchList = () => (branchesMemo === undefined ? (branchesMemo = src.branches()) : branchesMemo);
1103
1107
  const findings = []; // { level: 'fail'|'warn', text }
1104
1108
  // `self` = this target IS the handbook, not one of its consumers. Surfaced in the
1105
1109
  // report (and in --json) so the row reads as source-of-truth rather than clean-by-luck:
@@ -1608,7 +1612,12 @@ function auditRepo(target, ctx) {
1608
1612
  ? `tier A with deploy: tag requires trunk "dev" or "main", found ${JSON.stringify(trunk)}`
1609
1613
  : `tier A requires trunk "dev", found ${JSON.stringify(trunk)} — only a tag-gated A (deploy: tag) may run a single trunk "main"`);
1610
1614
  }
1611
- if (tier === "B" && trunk !== "main") fail(`tier B requires trunk "main", found ${JSON.stringify(trunk)}`);
1615
+ // #522: B is the single-trunk shape — one long-lived branch, any spelling. `master` (or
1616
+ // whatever an existing repo's default is) conforms; a "main" beside a non-main trunk does not.
1617
+ if (tier === "B") {
1618
+ const single = singleTrunkViolation(trunk, branchList());
1619
+ if (single) fail(`tier B requires a single trunk — ${single}`);
1620
+ }
1612
1621
  // C uses A's two-branch split: main = what is live, trunk = where sessions land. #205:
1613
1622
  // this validates the SPLIT, not the spelling — trunk is a declared setting (default
1614
1623
  // "dev", proposed by colab adopt and the templates), never required to literally be
@@ -1817,7 +1826,7 @@ function auditRepo(target, ctx) {
1817
1826
  // construction (CONVENTIONS.md §2: no mechanism rule applies to it, not even trunk shape).
1818
1827
  // A `runbook`-kind entry defers to `checkRunbook` here (this file can read the repo and tell
1819
1828
  // "missing" from "unreadable via the API"); every other entry is a ready `fail` message.
1820
- const shapeCtx = { trunk, hasProduction, deploy, hasDeployWorkflow: inRepoDeploy, deployWorkflowNames: [...deployWorkflows, ...fastDeployers] };
1829
+ const shapeCtx = { trunk, hasProduction, deploy, hasDeployWorkflow: inRepoDeploy, deployWorkflowNames: [...deployWorkflows, ...fastDeployers], branches: branchList() };
1821
1830
  for (const entry of evaluateExposure(exp, shapeCtx)) {
1822
1831
  if (entry.kind === "runbook") checkRunbook(src, runbook, fail, warn, entry.why);
1823
1832
  else fail(entry.message);
@@ -1825,7 +1834,7 @@ function auditRepo(target, ctx) {
1825
1834
  }
1826
1835
 
1827
1836
  // ---- declared trunk actually exists -------------------------------------
1828
- const branches = src.branches();
1837
+ const branches = branchList();
1829
1838
  if (trunk && branches === null) {
1830
1839
  warn(`cannot list branches (not a git checkout, or gh unavailable) — trunk "${trunk}" unverified`);
1831
1840
  } else if (trunk && branches && !branches.includes(trunk)) {
package/package.json CHANGED
@@ -32,5 +32,5 @@
32
32
  "engines": {
33
33
  "node": ">=18"
34
34
  },
35
- "version": "1.12.0-rc.69"
35
+ "version": "1.12.0-rc.71"
36
36
  }
package/tools/colab CHANGED
@@ -7718,6 +7718,18 @@ answered by its number OR its literal value), DERIVES the rest, and WRITES the d
7718
7718
  act — append-only, never touching a byte already there. A complete descriptor just reports
7719
7719
  (write nothing, exit 0); re-answer one row on purpose with --axis.
7720
7720
 
7721
+ ONLY THE GATING ROWS ARE ASKED (#533): deploy/production and exposure. room, writes and channels
7722
+ are optional and legal absent — never prompted for; the report names them in one line with the
7723
+ \`--axis\` command that answers each later, and their own flag still answers one in the same run.
7724
+ After deploy: none, production is not asked again (null follows; --deploy none alone implies it).
7725
+
7726
+ A SINGLE TRUNK, ANY SPELLING (#522): exposure none (and released with production null, and the
7727
+ legacy tier B) need ONE long-lived branch, not one named "main" — an existing master default
7728
+ adopts as-is. A "main" beside a non-main trunk is the two-branch shape and is refused (exit 5).
7729
+ At a terminal the exposure answer is checked against that shape when given, and re-asked with
7730
+ the reason. When a human must finish (the gate below), the FIRST line printed is the one
7731
+ command to run, every answer this run had already filled in.
7732
+
7721
7733
  --writes accepts free (coexistence, the default), direct (an attended human may commit straight
7722
7734
  to trunk; DECLARED today, its runtime is DEFERRED — see CONVENTIONS.md §2, "writes: direct —
7723
7735
  declared today, runtime deferred"), or isolated (vetoes trunk-direct outright, human or not).
@@ -7914,7 +7926,26 @@ function adoptGitExtras(repoAbs, opts = {}) {
7914
7926
  // #483: the fork's own owner, from origin's URL — what an inherited CODEOWNERS team is compared to.
7915
7927
  const originUrl = git.git(['remote', 'get-url', 'origin'], repoAbs);
7916
7928
  const ownOrg = originUrl.ok ? codeowners.remoteOwner(originUrl.stdout) : null;
7917
- return { trunk, trunkSource, hooksPath, hooksDirFiles, trackedFiles, fork: adoptDetectFork(repoAbs, opts), ownOrg };
7929
+ return { trunk, trunkSource, hooksPath, hooksDirFiles, trackedFiles, fork: adoptDetectFork(repoAbs, opts), ownOrg, branches: adoptBranchList(repoAbs) };
7930
+ }
7931
+
7932
+ /** #522: every branch name visible here — refs/heads ∪ refs/remotes/<any>/<name> — the same union
7933
+ * audit/audit.mjs's `branches()` reads, so the single-trunk rule (tools/lib/exposure-shape.js
7934
+ * `singleTrunkViolation`) answers identically on both sides: adopt never writes what the audit
7935
+ * then fails. null when git cannot list refs (the rule then fails closed to trunk "main"). */
7936
+ function adoptBranchList(repoAbs) {
7937
+ const r = git.git(['for-each-ref', '--format=%(refname)', 'refs/heads', 'refs/remotes'], repoAbs);
7938
+ if (!r.ok) return null;
7939
+ const names = new Set();
7940
+ for (const ref of r.stdout.split('\n').map((x) => x.trim()).filter(Boolean)) {
7941
+ if (ref.startsWith('refs/heads/')) names.add(ref.slice('refs/heads/'.length));
7942
+ else if (ref.startsWith('refs/remotes/')) {
7943
+ const rest = ref.slice('refs/remotes/'.length);
7944
+ const name = rest.slice(rest.indexOf('/') + 1);
7945
+ if (rest.includes('/') && name && name !== 'HEAD') names.add(name);
7946
+ }
7947
+ }
7948
+ return [...names];
7918
7949
  }
7919
7950
 
7920
7951
  /**
@@ -8187,6 +8218,8 @@ function printAdoptReport(report, repoAbs, verify, localFinish) {
8187
8218
  print(`detected trunk: ${t.detected || '(unknown)'}${trunkSourceNote}${t.declared !== null ? ` (declared: ${t.declared}${t.agree === false ? ' ⚠ disagrees with detected' : ''})` : ''}`);
8188
8219
  print(`stack candidates: ${report.detected.stackCandidates.length ? report.detected.stackCandidates.join(', ') : '(none found)'}`);
8189
8220
  print(`declared ports: ${fmtVal(report.detected.ports)}`);
8221
+ const optLine = adopt.optionalRowsLine(report.optionalUnanswered); // #533
8222
+ if (optLine) print(optLine);
8190
8223
  if (report.fork) print(`fork of an upstream: yes — ${report.fork.source === 'flag' ? '--fork' : `remote "${report.fork.remote}" ${report.fork.url}`} (step 5 is the append-only block, §9 "A fork of an upstream")`);
8191
8224
  if (report.inheritedCodeowners) {
8192
8225
  const ic = report.inheritedCodeowners;
@@ -8262,6 +8295,8 @@ function adoptAnswersFromFlags(opts, cfg, axesToAsk, forcedAxes) {
8262
8295
  if (!adopt.VALID_DEPLOY.has(opts.deploy)) throw new UserError(`--deploy must be one of: ${[...adopt.VALID_DEPLOY].join(', ')}`);
8263
8296
  values.deploy = opts.deploy;
8264
8297
  flags.push('--deploy');
8298
+ // #533: deploy: none already says nothing is live — production: null follows, never re-asked.
8299
+ if (opts.deploy === 'none' && opts.production === undefined && eligible('production', 'tier')) values.production = null;
8265
8300
  }
8266
8301
  if (flags.length) answers.tier = { values, mode: 'flag', flags };
8267
8302
  }
@@ -8325,7 +8360,7 @@ async function askMenu(rl, axis, promptFn) {
8325
8360
  * URL itself asked only on "yes" — this keeps every axis forced-choice-shaped without pretending
8326
8361
  * a URL belongs to an enum.
8327
8362
  */
8328
- async function adoptAskInteractive(rl, axesToAsk, cfg) {
8363
+ async function adoptAskInteractive(rl, axesToAsk, cfg, checkExposure) {
8329
8364
  const answers = {};
8330
8365
  for (const axis of axesToAsk) {
8331
8366
  const q = adopt.QUESTIONS.find((x) => x.axis === axis);
@@ -8336,13 +8371,16 @@ async function adoptAskInteractive(rl, axesToAsk, cfg) {
8336
8371
  process.stdout.write(`${adopt.renderMenu('tier')}\n`);
8337
8372
  return rlAsk(rl, ' deploy: ');
8338
8373
  });
8339
- process.stdout.write(' 1) no deploy target exists today\n 2) yes — enter the URL\n');
8340
- const existsRaw = (await rlAsk(rl, ' production: ')).trim();
8341
8374
  let prod = null;
8342
- if (existsRaw === '2' || existsRaw === 'yes') {
8343
- prod = (await rlAsk(rl, ' URL: ')).trim() || null;
8344
- } else if (existsRaw !== '1' && existsRaw !== 'no') {
8345
- throw new UserError('production: choose 1 (no deploy target exists today) or 2 (yes — enter the URL)');
8375
+ // #533: deploy: none already answered "nothing is live" — asking production again is noise.
8376
+ if (depChoice.value !== 'none') {
8377
+ process.stdout.write(' 1) no deploy target exists today\n 2) yes — enter the URL\n');
8378
+ const existsRaw = (await rlAsk(rl, ' production: ')).trim();
8379
+ if (existsRaw === '2' || existsRaw === 'yes') {
8380
+ prod = (await rlAsk(rl, ' URL: ')).trim() || null;
8381
+ } else if (existsRaw !== '1' && existsRaw !== 'no') {
8382
+ throw new UserError('production: choose 1 (no deploy target exists today) or 2 (yes — enter the URL)');
8383
+ }
8346
8384
  }
8347
8385
  answers.tier = { values: { production: prod, deploy: depChoice.value }, mode: 'interactive' };
8348
8386
  } else if (axis === 'channels') {
@@ -8352,12 +8390,22 @@ async function adoptAskInteractive(rl, axesToAsk, cfg) {
8352
8390
  });
8353
8391
  answers.channels = { values: { channels: resolved.value }, mode: 'interactive' };
8354
8392
  } else if (axis === 'exposure') {
8355
- const resolved = await askMenu(rl, 'exposure', () => {
8356
- process.stdout.write(`${adopt.renderMenu('exposure')}\n`);
8357
- return rlAsk(rl, ' choice: ');
8358
- });
8359
- if (resolved.skip) continue; // decline — the fallback tier derivation picks this up
8360
- answers.exposure = { values: { exposure: resolved.value }, mode: 'interactive' };
8393
+ // #522: the repo-shape check runs HERE, at answer time — a refusal re-asks with its reason,
8394
+ // instead of surfacing after every other question with nothing written.
8395
+ let chosen = null;
8396
+ for (let attempt = 0; attempt < 2 && !chosen; attempt++) {
8397
+ const resolved = await askMenu(rl, 'exposure', () => {
8398
+ process.stdout.write(`${adopt.renderMenu('exposure')}\n`);
8399
+ return rlAsk(rl, ' choice: ');
8400
+ });
8401
+ if (resolved.skip) { chosen = resolved; break; }
8402
+ const problem = checkExposure ? checkExposure(resolved.value, answers) : null;
8403
+ if (!problem) { chosen = resolved; break; }
8404
+ process.stdout.write(` ✗ ${problem}\n choose again (or skip):\n`);
8405
+ }
8406
+ if (!chosen) throw new UserError('exposure: no answer this repo\'s shape supports after one re-prompt');
8407
+ if (chosen.skip) continue; // decline — the fallback tier derivation picks this up
8408
+ answers.exposure = { values: { exposure: chosen.value }, mode: 'interactive' };
8361
8409
  } else {
8362
8410
  // room, writes — plain single-choice menus, no skip.
8363
8411
  const resolved = await askMenu(rl, axis, () => {
@@ -8370,11 +8418,41 @@ async function adoptAskInteractive(rl, axesToAsk, cfg) {
8370
8418
  return answers;
8371
8419
  }
8372
8420
 
8421
+ /** #522: this run's answers as the ordered flag list `adopt.humanAdoptCommand` prints — what the
8422
+ * human pastes to finish the same adoption with the gate satisfied. */
8423
+ function adoptReplayFlags(opts, answers) {
8424
+ const flags = [];
8425
+ if (opts.repo !== undefined) flags.push(['--repo', opts.repo]);
8426
+ const t = answers.tier && answers.tier.values;
8427
+ if (t && 'production' in t) flags.push(['--production', t.production === null ? 'none' : t.production]);
8428
+ if (t && 'deploy' in t) flags.push(['--deploy', t.deploy]);
8429
+ if (answers.exposure) flags.push(['--exposure', answers.exposure.values.exposure]);
8430
+ if (answers.room) flags.push(['--room', answers.room.values.room]);
8431
+ if (answers.writes) flags.push(['--writes', answers.writes.values.writes]);
8432
+ if (answers.channels) flags.push(['--channels', answers.channels.values.channels.join(',')]);
8433
+ if (opts.stack !== undefined) flags.push(['--stack', opts.stack]);
8434
+ if (opts.autonomy !== undefined) flags.push(['--autonomy', opts.autonomy]);
8435
+ if (opts.reason !== undefined) flags.push(['--reason', opts.reason]);
8436
+ if (opts.answeredBy) flags.push(['--answered-by', opts.answeredBy]);
8437
+ if (opts.land) flags.push(['--land', true]);
8438
+ return flags;
8439
+ }
8440
+
8441
+ /** #522: the same command shape for a run that had no answers at all — placeholders per asked row. */
8442
+ function adoptAskedFlagPlaceholders(axesToAsk, stackUnresolvable) {
8443
+ const flags = [];
8444
+ if (axesToAsk.includes('tier')) flags.push(['--production', '<url>|none'], ['--deploy', '<none|tag|manual|push-main>']);
8445
+ if (axesToAsk.includes('exposure')) flags.push(['--exposure', '<none|self|live|released>']);
8446
+ for (const a of ['room', 'writes', 'channels']) if (axesToAsk.includes(a)) flags.push([`--${a}`, `<${a}>`]);
8447
+ if (stackUnresolvable) flags.push(['--stack', '<text>']);
8448
+ return flags;
8449
+ }
8450
+
8373
8451
  /** The `EXPOSURE_SHAPE`/falsifier context, built from EFFECTIVE production/deploy — accounting
8374
8452
  * for a `tier`-axis answer resolved in THIS SAME run, not only what was already on record, so
8375
8453
  * declaring production+deploy and exposure together in one invocation validates against each
8376
8454
  * other rather than the pre-write snapshot. */
8377
- function adoptShapeCtx(cfg, tierAnswer, trunk, workflows, io) {
8455
+ function adoptShapeCtx(cfg, tierAnswer, trunk, workflows, io, branches) {
8378
8456
  const effProduction = tierAnswer ? tierAnswer.values.production : (Object.prototype.hasOwnProperty.call(cfg, 'production') ? cfg.production : null);
8379
8457
  const effDeploy = tierAnswer ? tierAnswer.values.deploy : (Object.prototype.hasOwnProperty.call(cfg, 'deploy') ? cfg.deploy : null);
8380
8458
  const evidence = consumerEvidence.consumerEvidence(io, workflows);
@@ -8382,7 +8460,7 @@ function adoptShapeCtx(cfg, tierAnswer, trunk, workflows, io) {
8382
8460
  const hasProduction = effProduction !== null && effProduction !== undefined && effProduction !== '';
8383
8461
  const runbook = Object.prototype.hasOwnProperty.call(cfg, 'runbook') ? cfg.runbook : null;
8384
8462
  const hasRunbook = !!(runbook && io.readFile(String(runbook).trim().replace(/^\.\//, '')) !== null);
8385
- return { trunk, hasProduction, deploy: effDeploy, hasDeployWorkflow, hasRunbook, effProduction, effDeploy };
8463
+ return { trunk, hasProduction, deploy: effDeploy, hasDeployWorkflow, hasRunbook, effProduction, effDeploy, branches: branches === undefined ? null : branches };
8386
8464
  }
8387
8465
 
8388
8466
  async function cmdAdopt(argv) {
@@ -8428,7 +8506,12 @@ async function cmdAdopt(argv) {
8428
8506
  if (!adopt.ROW_NAMES.includes(a)) throw new UserError(`Unknown --axis "${a}" — expected one of: ${adopt.ROW_NAMES.join(', ')}`);
8429
8507
  }
8430
8508
  const forcedAxes = new Set(requestedAxes);
8431
- let axesToAsk = adopt.ROW_NAMES.filter((a) => forcedAxes.has(a) || adopt.axisMissing(cfg, a));
8509
+ // #533: a fresh adoption asks only the rows that change a gate (production/deploy, exposure);
8510
+ // room/writes/channels are asked only when forced (--axis) or answered by their flag.
8511
+ const flagAxes = new Set();
8512
+ if (opts.production !== undefined || opts.deploy !== undefined) flagAxes.add('tier');
8513
+ for (const a of ['room', 'exposure', 'writes', 'channels']) if (opts[a] !== undefined) flagAxes.add(a);
8514
+ let axesToAsk = adopt.axesToAsk(cfg, forcedAxes, flagAxes);
8432
8515
  // --local re-run (#393): once exposure is on record, a bare `adopt --local` (no answer flags, no
8433
8516
  // --axis) is the idempotent re-apply — exclude lines, stub, labels, checkout — never a prompt for
8434
8517
  // the optional rows (room/writes/channels), which --local leaves to the operator by design.
@@ -8522,7 +8605,11 @@ async function cmdAdopt(argv) {
8522
8605
  } else if (isTTY) {
8523
8606
  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
8524
8607
  try {
8525
- answers = await adoptAskInteractive(rl, axesToAsk, cfg);
8608
+ const shapeWorkflows = io.listDir('.github/workflows').filter((f) => /\.ya?ml$/.test(f));
8609
+ answers = await adoptAskInteractive(rl, axesToAsk, cfg, (exposure, sofar) => {
8610
+ const v = adopt.exposureShapeVerdict(exposure, adoptShapeCtx(cfg, sofar.tier, extra.trunk, shapeWorkflows, io, extra.branches));
8611
+ return v.ok ? null : v.reason;
8612
+ });
8526
8613
  if (needsStack && opts.stack === undefined) {
8527
8614
  process.stdout.write('\nNo manifest recognised (package.json/composer.json/pyproject.toml/'
8528
8615
  + '.python-version) — the audit requires stack: as a literal key.\n');
@@ -8537,6 +8624,12 @@ async function cmdAdopt(argv) {
8537
8624
  } else {
8538
8625
  const hints = axesToAsk.map(adoptAxisFlagHint).join(' ');
8539
8626
  const stackHint = stackUnresolvable ? ' --stack "<text>"' : '';
8627
+ // #522: the human step goes FIRST — answering exposure none/self is a human's act, so the one
8628
+ // command that finishes the adoption leads, and the explanation follows it.
8629
+ if (axesToAsk.includes('exposure')) {
8630
+ warn('a human finishes this adoption — run at an interactive terminal: colab adopt (or, non-interactively:)');
8631
+ warn(` ${adopt.humanAdoptCommand(adoptAskedFlagPlaceholders(axesToAsk, stackUnresolvable))}`);
8632
+ }
8540
8633
  warn(`${axesToAsk.length} unanswered §9 row(s) (${axesToAsk.join(', ')}) — no TTY and no answer flags, so there is no way to ask. Re-run with: ${hints}${stackHint}`);
8541
8634
  return 1;
8542
8635
  }
@@ -8561,7 +8654,7 @@ async function cmdAdopt(argv) {
8561
8654
  // written, per "nothing partially written on refusal".
8562
8655
  if (answers.exposure) {
8563
8656
  const proposedExposure = answers.exposure.values.exposure;
8564
- const shapeCtx = adoptShapeCtx(cfg, answers.tier, trunk, workflows, io);
8657
+ const shapeCtx = adoptShapeCtx(cfg, answers.tier, trunk, workflows, io, extra.branches);
8565
8658
  const evidence = consumerEvidence.consumerEvidence(io, workflows);
8566
8659
  const currentExposure = axisAuthority.axisOfRecord(cfg).exposure;
8567
8660
  const verdict = adopt.gateVerdict({
@@ -8575,6 +8668,10 @@ async function cmdAdopt(argv) {
8575
8668
  reason: opts.reason || null,
8576
8669
  });
8577
8670
  if (!verdict.ok) {
8671
+ if (verdict.class === adopt.GATE_CLASS.HUMAN_GATED) {
8672
+ // #522: lead with the one command a human runs, every answer this run had filled in.
8673
+ warn(`a human finishes this adoption — run: ${adopt.humanAdoptCommand(adoptReplayFlags(opts, answers))}`);
8674
+ }
8578
8675
  warn(verdict.message);
8579
8676
  return verdict.exitCode;
8580
8677
  }
@@ -37,6 +37,13 @@ const { UserError } = require('./util.js');
37
37
 
38
38
  const ROW_NAMES = ['tier', 'room', 'exposure', 'writes', 'channels'];
39
39
 
40
+ /** #533: the rows that change a gate — the only ones a fresh adoption ASKS. `tier` here is the
41
+ * production/deploy pair; `exposure` sets the gate count. The other three are optional in the
42
+ * schema and legal absent (room → trail verbosity, writes → `free` is the default, channels →
43
+ * descriptive), so adoption leaves them unanswered and names the `--axis` command instead. */
44
+ const GATING_ROWS = Object.freeze(['tier', 'exposure']);
45
+ const OPTIONAL_ROWS = Object.freeze(['room', 'writes', 'channels']);
46
+
40
47
  // ---------------------------------------------------------------------- descriptor read
41
48
 
42
49
  /** Parsed `.github/project.yml`, or {} when absent/unparseable — never throws. */
@@ -387,7 +394,7 @@ function remainingSteps(ctx = {}) {
387
394
  if (ctx.migrations) steps.push({ n: 2, text: migrationsStepText(ctx.migrations) });
388
395
  steps.push(
389
396
  { n: 3, text: 'Create the full label set (21 names) — `colab labels --ensure`, CONVENTIONS.md §9 step 3 (#206)' },
390
- { n: 4, text: 'Add the tier topic to the GitHub repo — `gh repo edit --add-topic tier-<b|c|a>`, step 4' },
397
+ { n: 4, text: 'Optional: add the tier topic to the GitHub repo — `gh repo edit --add-topic tier-<b|c|a>`, step 4. Needs repo ADMIN (push access alone gets `HTTP 404 …/topics`); nothing in colab or the audit reads it, so skip it when you are not one (#522)' },
391
398
  );
392
399
  if (ctx.fork) {
393
400
  steps.push({ n: 5, text: `Fork of an upstream (${ctx.fork.source === 'flag' ? '--fork' : `remote "${ctx.fork.remote}"`}): do NOT make CLAUDE.md the thin shell — append templates/repo-CLAUDE-block.md at the END of the upstream's CLAUDE.md (create it only if upstream has none), record that append as a fork patch, leave AGENTS.md and the upstream prose untouched; CONVENTIONS.md §9 "A fork of an upstream", step 5` });
@@ -538,6 +545,7 @@ function detect(io, extra = {}) {
538
545
  inheritedCodeowners,
539
546
  migrations,
540
547
  remaining: remainingSteps({ migrations, fork, upstreamAgentFiles, releaseRung }),
548
+ optionalUnanswered: optionalUnanswered(cfg), // #533
541
549
  };
542
550
  }
543
551
 
@@ -780,6 +788,52 @@ function axisMissing(cfg, axis) {
780
788
  }
781
789
  }
782
790
 
791
+ /**
792
+ * #533: which rows this run asks. A gating row is asked when it is still missing; an optional row
793
+ * (room/writes/channels) only when the caller forced it (`--axis`) or supplied its answer flag —
794
+ * a fresh adoption never prompts for it. `flagAxes` — the rows an answer flag was given for.
795
+ */
796
+ function axesToAsk(cfg, forcedAxes, flagAxes) {
797
+ const forced = forcedAxes instanceof Set ? forcedAxes : new Set(forcedAxes || []);
798
+ const flagged = flagAxes instanceof Set ? flagAxes : new Set(flagAxes || []);
799
+ return ROW_NAMES.filter((a) => forced.has(a)
800
+ || (axisMissing(cfg, a) && (GATING_ROWS.includes(a) || flagged.has(a))));
801
+ }
802
+
803
+ /** #533: the optional rows still unanswered after a run — reported in one line, never asked. */
804
+ function optionalUnanswered(cfg) {
805
+ return OPTIONAL_ROWS.filter((a) => axisMissing(cfg, a));
806
+ }
807
+
808
+ /** The one line naming them and the command that answers each later (#533). null when none. */
809
+ function optionalRowsLine(rows) {
810
+ if (!rows || !rows.length) return null;
811
+ return `not asked (optional, legal absent): ${rows.join(', ')} — answer later with \`colab adopt --axis ${rows.join(',')}\``;
812
+ }
813
+
814
+ /** Shell-quote one argument only when it needs it — the printed command must paste and run. */
815
+ function shellArg(v) {
816
+ const t = String(v);
817
+ return /^[A-Za-z0-9_@%+=:,./-]+$/.test(t) ? t : `"${t.replace(/(["\\$`])/g, '\\$1')}"`;
818
+ }
819
+
820
+ /**
821
+ * #522: the ONE command a human runs to finish an adoption an agent could not — printed as the
822
+ * first line of a human-gated refusal, answers already filled in. `flags` is an ordered list of
823
+ * `[flag, value]` pairs (value undefined/null for a bare flag); `--answered-by` is appended as a
824
+ * placeholder when absent, because the human bar needs it alongside COLAB_HUMAN=1.
825
+ */
826
+ function humanAdoptCommand(flags) {
827
+ const parts = ['COLAB_HUMAN=1', 'colab', 'adopt'];
828
+ let hasAnsweredBy = false;
829
+ for (const [flag, value] of flags || []) {
830
+ if (flag === '--answered-by') hasAnsweredBy = true;
831
+ parts.push(value === undefined || value === null || value === true ? flag : `${flag} ${shellArg(value)}`);
832
+ }
833
+ if (!hasAnsweredBy) parts.push('--answered-by "<your name>"');
834
+ return parts.join(' ');
835
+ }
836
+
783
837
  // ---------------------------------------------------------------------- EXPOSURE_SHAPE — the constructor
784
838
 
785
839
  /**
@@ -1166,6 +1220,12 @@ module.exports = {
1166
1220
  renderMenu,
1167
1221
  resolveChoice,
1168
1222
  axisMissing,
1223
+ GATING_ROWS,
1224
+ OPTIONAL_ROWS,
1225
+ axesToAsk,
1226
+ optionalUnanswered,
1227
+ optionalRowsLine,
1228
+ humanAdoptCommand,
1169
1229
  EXPOSURE_RANK,
1170
1230
  GATE_CLASS,
1171
1231
  EXIT_CODE,
@@ -53,7 +53,8 @@
53
53
  * Context shape both sides build (identically named, audit.mjs and adopt.js each computing the
54
54
  * booleans from their own sources — a real git checkout for one, a `git status`-aware `io` for
55
55
  * the other):
56
- * { trunk, hasProduction, deploy, hasDeployWorkflow, hasRunbook, deployWorkflowNames? }
56
+ * { trunk, hasProduction, deploy, hasDeployWorkflow, hasRunbook, deployWorkflowNames?, branches? }
57
+ * `branches` (#522) is what `singleTrunkViolation` reads — omitting it fails closed to trunk "main".
57
58
  * `deployWorkflowNames` is OPTIONAL and cosmetic only (the `none` violation names which
58
59
  * workflow(s) contradict it) — omitting it (as adopt.js's ctx does) only drops the parenthetical
59
60
  * from the message, never changes which entries fire.
@@ -74,13 +75,45 @@ function evaluateExposure(exposure, ctx) {
74
75
  }
75
76
  }
76
77
 
78
+ /**
79
+ * #522: the single-trunk invariant shared by every shape with no release branch — `exposure: none`,
80
+ * `exposure: released` with `production: null`, and the legacy `tier: B` (audit/audit.mjs). It is
81
+ * about HOW MANY long-lived branches exist, never how the one branch is spelled: an existing repo
82
+ * whose default branch is `master` (or anything else) adopts as-is, with nothing renamed.
83
+ *
84
+ * What it refuses is the two-branch shape wearing a single-trunk label: a `main` branch sitting
85
+ * beside a trunk that is not `main` is the live/released split (main = what ships, trunk = where
86
+ * sessions land), and declaring "nothing consumes this" over it would hide the release branch.
87
+ *
88
+ * `branches` — every branch name the caller can see (local ∪ remote-tracking), or null/undefined
89
+ * when it cannot list them. Unknown FAILS CLOSED to the old spelling rule (trunk "main"): a
90
+ * non-main trunk is accepted only when a readable branch list proves no `main` sits beside it.
91
+ *
92
+ * Returns null when the invariant holds, else the reason text (no prefix — each caller names its
93
+ * own shape in front of it).
94
+ */
95
+ function singleTrunkViolation(trunk, branches) {
96
+ if (!trunk) return `no trunk declared, found ${JSON.stringify(trunk)}`;
97
+ if (trunk === 'main') return null;
98
+ if (!Array.isArray(branches)) {
99
+ return `trunk ${JSON.stringify(trunk)} can stand in for "main" only when the branch list is readable `
100
+ + 'and shows no "main" beside it, and the branch list could not be read';
101
+ }
102
+ if (branches.includes('main')) {
103
+ return `trunk is ${JSON.stringify(trunk)} and a "main" branch exists beside it — that is the `
104
+ + 'two-branch (live/released) shape, not a single trunk';
105
+ }
106
+ return null;
107
+ }
108
+
77
109
  function evaluateNone(ctx) {
78
110
  const out = [];
79
- if (ctx.trunk !== 'main') {
111
+ const single = singleTrunkViolation(ctx.trunk, ctx.branches);
112
+ if (single) {
80
113
  out.push({
81
114
  kind: 'fail',
82
- message: `exposure: none requires trunk "main", found ${JSON.stringify(ctx.trunk)} — nothing `
83
- + 'consumes this repo, so there is no release branch to speak of',
115
+ message: `exposure: none requires a single trunk — ${single} — nothing consumes this repo, `
116
+ + 'so there is no release branch to speak of',
84
117
  });
85
118
  }
86
119
  if (ctx.hasDeployWorkflow) {
@@ -131,11 +164,12 @@ function evaluateLive(ctx) {
131
164
 
132
165
  function evaluateReleasedNoProduction(ctx) {
133
166
  const out = [];
134
- if (ctx.trunk !== 'main') {
167
+ const single = singleTrunkViolation(ctx.trunk, ctx.branches);
168
+ if (single) {
135
169
  out.push({
136
170
  kind: 'fail',
137
- message: `exposure: released with production: null requires trunk "main", found `
138
- + `${JSON.stringify(ctx.trunk)} — nothing is live, so there is no release branch to speak of`,
171
+ message: `exposure: released with production: null requires a single trunk — ${single} — `
172
+ + 'nothing is live, so there is no release branch to speak of',
139
173
  });
140
174
  }
141
175
  if (ctx.deploy !== null && ctx.deploy !== undefined && ctx.deploy !== 'none') {
@@ -204,4 +238,4 @@ function evaluateReleasedWithProduction(ctx) {
204
238
  return out;
205
239
  }
206
240
 
207
- module.exports = { evaluateExposure };
241
+ module.exports = { evaluateExposure, singleTrunkViolation };
@@ -13,8 +13,9 @@
13
13
  *
14
14
  * Row severities, and the one rule behind them: ✗ (fail, exit 1) means something was INSTALLED and
15
15
  * is now stale or unusable; ⚠ means something was simply never set up, which may be a deliberate
16
- * choice (a machine that only wants the skills needs no fleet list). A report that failed every
17
- * skills-only machine would teach people to ignore its exit code.
16
+ * choice (a machine that only wants the skills needs no fleet list) or just not done YET (no repo
17
+ * registered, no identity vocabulary). A report that failed every skills-only machine — or every
18
+ * correct fresh `--all` install, as it did until #521 — would teach people to ignore its exit code.
18
19
  *
19
20
  * CommonJS, zero dependencies, runnable as a script: install.sh calls
20
21
  * node tools/lib/install-check.js --root <handbook> --colab-home <dir> --home <dir>
@@ -163,9 +164,9 @@ function checkState({ root, colabHome, home }) {
163
164
  }
164
165
 
165
166
  /**
166
- * The fleet: both machine-local registries `colab register` writes. A repos.txt that exists with no
167
- * live entry is the `--fleet` dead end — seeded from placeholders, and the next command refuses with
168
- * "No repos registered". That one is a ✗; never having asked for a fleet is a ⚠.
167
+ * The fleet: both machine-local registries `colab register` writes. Nothing registered is ⚠ whether or
168
+ * not `--fleet` seeded the placeholder list: both are "not set up yet", the state every correct fresh
169
+ * install is in until its first `colab register` (#521). The ⚠ text still names the dead end.
169
170
  */
170
171
  function checkFleet({ colabHome }) {
171
172
  const rows = [];
@@ -179,7 +180,9 @@ function checkFleet({ colabHome }) {
179
180
  if (entries === null && !cfgRepos.length) {
180
181
  rows.push({ area: 'fleet', severity: WARN, text: `nothing registered — add each repo: colab register <path>` });
181
182
  } else if (entries !== null && !entries.length) {
182
- rows.push({ area: 'fleet', severity: FAIL, text: `${txtFile} exists with no live entry (placeholders only) — \`colab update\`/\`colab release-status\` refuse "No repos registered". Fix: colab register <path>` });
183
+ // #521: this is exactly what `--fleet` leaves on a new machine, and the install's own "next" list
184
+ // says to register a repo. Not yet set up, not broken — a ✗ here failed every correct fresh install.
185
+ rows.push({ area: 'fleet', severity: WARN, text: `nothing registered yet — ${txtFile} holds placeholders only, so \`colab update\`/\`colab release-status\` refuse "No repos registered". Next: colab register <path>` });
183
186
  } else {
184
187
  const locals = (entries || []).filter((e) => e.startsWith('/') || e.startsWith('~'));
185
188
  const unmirrored = locals.filter((e) => !cfgRepos.includes(e));
@@ -196,6 +199,9 @@ function checkFleet({ colabHome }) {
196
199
  * first hooklet's dependency) and said nothing about the identity vocabulary the second needs — and
197
200
  * the second guards publication to a public repo. With no vocabulary it warns and passes every commit.
198
201
  * Resolution order mirrors templates/pre-commit-identity exactly.
202
+ *
203
+ * Both dependencies are ⚠, never ✗ (#521): the preflight calls them optional, and a missing one is
204
+ * something not set up yet, not an install gone stale. Symmetric still — neither row is quieter.
199
205
  */
200
206
  function checkHooks({ root, colabHome, home, env }) {
201
207
  const hp = gitConfig(root, 'core.hooksPath', env);
@@ -206,7 +212,7 @@ function checkHooks({ root, colabHome, home, env }) {
206
212
  const rows = [];
207
213
  rows.push(isExecutable('gitleaks', env)
208
214
  ? { area: 'hooks', severity: OK, text: 'gitleaks on PATH — the secret scan runs' }
209
- : { area: 'hooks', severity: FAIL, text: 'gitleaks not on PATH — the secret-scan hooklet skips every commit (macOS: brew install gitleaks)' });
215
+ : { area: 'hooks', severity: WARN, text: 'gitleaks not on PATH — the secret-scan hooklet skips every commit (macOS: brew install gitleaks)' });
210
216
 
211
217
  let vocab; let src;
212
218
  if (env.COLAB_IDENTITY_VOCAB) { vocab = env.COLAB_IDENTITY_VOCAB; src = 'COLAB_IDENTITY_VOCAB'; }
@@ -215,7 +221,7 @@ function checkHooks({ root, colabHome, home, env }) {
215
221
  if (vocab.startsWith('~/')) vocab = path.join(home, vocab.slice(2));
216
222
  rows.push(readText(vocab) !== null
217
223
  ? { area: 'hooks', severity: OK, text: `identity vocabulary ${vocab} (${src}) — the identity scan runs` }
218
- : { area: 'hooks', severity: FAIL, text: `no identity vocabulary at ${vocab} (${src}) — the identity hooklet warns and lets every commit through. Example: templates/identity-vocabulary.example` });
224
+ : { area: 'hooks', severity: WARN, text: `no identity vocabulary at ${vocab} (${src}) — the identity hooklet warns and lets every commit through. Example: templates/identity-vocabulary.example` });
219
225
  return rows;
220
226
  }
221
227